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Microsoft Speech SDK 
with SAPI 5.0 



[This is preliminar>' documentation and subject to change.] 



The following structures are used with SAPI 5. 

• SPAUDIOBUFFERINFO 

• SPAUDIOSTATUS 

• SPBINARYGMMMAR 
. "SPEVENT 

• SPEVENTSOURCEINFO 

• SPPARSEWO 

• sppAthentry 

• spphrase 

• spphrasealt 

• spphrasealtrequest 

• spphraseelement 

• spphraseproperty 

• spphMseMplacement 

• SPPHRASERULE 

• SPPROPERTYINFO 

• SPRECOCONTEXTSTATUS 

• SPRJECOGNiZERSTATUS 

• SPRECORESULtlNFO 

• SPRECORESULTTIMES 
. SPRtfLEENTRY 

• SPSERiALiZEDEVENT 

• SPSERiALiZEDPHRASE 

• SPSERIALIZEDRESULt 

• SPSTATEINFO 

• SPTEXTSELECTIONINFO 

• SPTMTHREADINFO 

• SPTRANSmONENTRY 

• SPTRANSmONPROPERTY 

• SPVCONTEXT 

• SPVOICESTAtUS 

• SPVPlf CH 

• spvsentitem 

• spvstate 

• spvTextfrag 

• SPWORD 

• SPWORDENTRY 

• SPWORDLISf 

• SPWORDPRONUNCIATION 

• SPWORDPRONUNCIATION^ 

• WAVEFORMATEX 
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[This is preliminary documentation and subject to change,] 

SPAUDIOBUFFERINFO 

SPAUDIOBUFFERINFO contains the audio stream buffer information. 

typedef struct SPAUDIOBUFFERINFO 

^ ULONG ulMsMinNotification} 

ULONG ulMsBufferSize; 

ULONG u IMsEven tBias; 

} SPAUDIOBUFFERINFO; 

Members 

UlMsMinNotification 

The minimum desired time, in milliseconds, allowed between the actual time an event 
notification occurs and the ideal time. The smaller this number is, the more CPU overhead is 
required, but the event notifications will be more timely. This value must be at most one 
quarter the size of the ulMsBuffersize. 

ulMsBufferSize , * i • • i 

The size of the audio object's buffer, in milliseconds. For readable audio objects, this is simply 
a desired size - readable objects will automatically expand their buffers to accommodate data. 
For writeable audio objects, this is the amount of audio data that will be buffered before a call 
to Write v^U block, 

ulMsEventBias 

The amount of time, in milliseconds, that events will be completed before they actually occur. 
For example, setting a value of 100 for the event bias would cause all events to be notified 100 
miUiseconds prior to the audio data being played. This can be useful for applications needing 
time to animate mouths for synthetic speech. 

© 1995-2000 MLcrospft Coiporatjon. All jijihts reserved. 
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SPAUDIOSTATUS 



typedef [restricted] struct SPAUDIOSTATUS 

^ " cbFreeBuff Space; 

cbNonBl ockinglO ; 
State; 
CurSeekPos; 
CurDevi cePos ; 
dwReservedl ; 
dwReserved2 ; 



long 
ULONG 

SPAUDIOSTATE 
ULONGLONG 
ULONGLONG 
DWORD 
DWORD 
} SPAUDIOSTATUS; 



Members 
cbFreeBuffiSpace 

Size, in bytes, of free space for reading and/or writing in the audio object. 
cbNonBlockinglO 
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State 

The state of type SPAUDIOSTATE of the audio device. 
CurSeekPos 

The current seek position, in bytes, vvdthin the audio stream. This is the position in the stream at 
which the next read or write will be performed. 
CurDevicePos 

The current read position, in bytes, of the device. This is the position in the stream where the 
device is currently reading or writing. For readable streams, this value will always be greater 
than or equal to CurSeekPos. For writeable streams, this value will always be less than or equal 
to CurSeekPos. 

dwReservedl 

Reserved for future expansion. 

dwReserved2 

Reserved for future expansion. 



© 1995-2000 Microsoft Corp_pMipn. All rights reser\^d 
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SPBINARYGRAMMAR 



SPBINARYGRAMMAR contains the grammar size information. 



typedef struct SPBINARYGRAMMAR 

^ ULONG ulTotalSerializedSize; 
} SPBINARYGRAMMAR; 



Members 



UlTotalSerializedSize 

Total size, in bytes, of the serialized grammar. 



© 1995-2000 Micrpsoftj::o_rporati reserved. 
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SPEVENT 



SPEVENT passes back information about event objects. 



typedef struct 
{ 



SPEVENT 



eEventId : 16; 

elParamType : 16; 

ulStreamNum; 

ullAudioStreamOffset; 

wParam ; 

iParamj 



int 
int 
ULONG 
ULONGLONG 



WPARAM 
IiPARAM 



} SPEVENT; 



Members 
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eEventId : 16 

The event ID of type SPEVENTENUM- 
elParamType : 16; 

The parameter type of type SPEVENTLPARAMTYPE. 

eEventId . . r. , 

The event ID. This ID contains flags used to define the charactenstic of the event. Three 
characteristics are defined. Event Flags identify each event as separate depending on the 
context or the event source. Private Driver Code stores driver-dependent relationships. The 
pointer flag to IParam indicates that the LParam field of SPEVENT points to vaUd 
information. In this case, the wParam field stores the size of the structure. 
ulStreamNum , ^ , , . . 

The input stream number of the ISpVoice:: Speak or ISp Voice:; SpeakStream method associated 

with the event. 

ullAudioStreamOffset , . , ...... 

An offset with the audio stream for the event. For synthesis, the output is the synthesized data. 
For recognition, this indicates the required audio stream. 

wP ft 1*3111 

The generic word field. For event IDs with the SPFEI_LPARAM_IS_POINTER set, this is the 
size, in bytes, for the data pointed to by IParam. In some cases, the type of event will change 
the function of this parameter. See SPEVENTENUM for information about specific events. 
LPftfftiu 

The generic event field. For event IDs with the SPFEI_LPARAM_IS_POINTER set, this 
points to the data allocated by CoTaskMemAlloc. The caller is responsible for fi-eeing this 
memory using CoTaskMemFreeQ. In some cases, the type of event will change the fimction of 
this parameter. See SPEVENTHWM for information about specific events. 

© 1995-20.00 MiqrosoftCorporatipn..Ali rights reserved. 



[This is preliminary documentation and subject to change.] 

SPEVENTSOURCEINFO 

A structure used by ISpEventSource::GetInfo to pass back event information. 

typedef struct SPEVENTSOURCEINFO 

^ ULONGLONG ullEventlnterest; 

ULONGLONG ullQueuedlnterest; 

ULONG ulCount; 
} SPEVENTSOURCEINFO; 

Members 

uUEventlnterest _ , . ^ . 

Event ID flags of type SPEVENTENUM marking events which mvoke a notification. 

ullQueuedlnterest 

Queue of event IDs. These remain until ISpEventSource::GetEvents removes them. 
ulCount 

Number of events currently queued. 

© i995-200p_Mjcrpsoft Con)oration AlLrmhts reserved. 
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[This is preliminary documentation aiid subject to change.] 

SPPARSEINFO 



typedef struct SPPARSEINFO 
{ 

ULONG 

SPRULEHANDLE 
ULONGLONG 
ULONG 
ULONG 

SPPATHENTRY 
BOOL 
GUID 
ULONG 
const BYTE 
} SPPARSEINFO; 



cbSize; 
hRule; 

ul lAudi oS treamPosi tlon; 
ulAudioSize; 
cTransitions; 
*pPath; 
f Hypothesis; 
SREnginelD; 

ulSREnginePri va t eDa taSi ze ; 
*pSREnginePri va teDa ta ; 



Members 



cbSize 
hRule 

ullAudioStreamPosition 

ulAudioSke 

cTransitions 

pPath 

fHypotliesis 

SREnginelD 

ulSREnginePrivateDataSize 
pSREnginePrivateData 

© l_995:2pOO__Micro_soft Corppratigii, AJ] riah^ reserv_ed. 
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SPPATHENTRY 



typedef [restricted] struct SPPATHENTRY 
{ 

union 

^ SPTRANSITIONID hTransition; 
SPPHRASEELEMENT elem; 

} SPPATHENTRY; 



Members 



hTransition 
elem 
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file://C:\WINDOWS\TEMP\^hh4B4E.htm 



12/28/00 



Structures 



Page 6 of 26 



[This is preliminary documentation and subject to change.] 

SPPHRASE 



typedef [restricted] struct 

ULONG 
LANGID 
WORD 

ULONGLONG 
ULONGLONG 
ULONG 
ULONG 

SPPHRASERXILE 
const" SPPHRASEPROPBRTY 
const SPPHRASEELEMENT 
ULONG 

const SPPHRASEREPLACEMENT 
GUID 
ULONG 
const BYTE 
} SPPHRASE; 



SPPHRASE 

cbSize; 
LangID; 
wReserved) 
ftStartTime; 
ul lAu di oS treamPosi tion; 
ulAudioSizeBytes ; 
ulAudi oSizeTime ; 
Rule; 

* pProperties'f 

* pElements; 
cReplacementS', 

* pReplacements; 
SREnginelD} 

ulSREnginePrivateDataSize; 

* pSREnglnePrivateData; 



Members 



cbSize 

The size of this structure in bytes, 
LangID 

The language ID of the current language. 
wReserved 

Reserved for future use. 
ftStartTime 

ullAudioStreamPosition 
UlAudioSizeBytes 
ulAudioSizeTime 
Rule 

pProperties 

pEIements 

cReplacements 

pReplacements 

SREnginelD 

UlSREnginePrivateDataSize 
pSREnginePrivateData 

© 1995-2000 Microsoft Corporation. AH rights resen'ed 
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SPPHRASEALT 



typedef struct tagSPPHRASEALT 

^ ISpPhraseBuilder *pPhrase; 

ULONG ulStartElementlnParent; 
ULONG cEl emen tsInParen t ; 
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ULONG cEl emen tsInAl terna te ; 

void *pvAltExtra; 
ULONG cbAl tExtra ; 

} SPPHRASEALT; 



Members 
pPhrase 

ulStartElementlnParent 

cElementsInParent 

cElementsInAIternate 

pvAltExtra 

cbAItExtra 

© .1995-2000 Microspft Cojppration._ Aji rights jeserved 
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SPPHRASEALTREQUEST 



typedef struct tagSPPHRASEALTREQUEST 
{ 

ULONG ulStartElement ; 

ULONG cE 1 ement s ; 

ULONG ulRequestAltCount ; 

void * pvResul tExtra; 

ULONG cbResul tExtra; 

ISpPhrase * pPhrase; 
I SpRecoCont ext * pRecoContext ; 
} SPPHRASEALTREQUEST; 

Members 

UlStartElement 

cEIements 

UlRequestAltCount 

pvResultExtra 

cbResultExtra 

pPhrase 

pRecoContext 



© 19?5-_200_0 Micrp_soft Cqrppratipn AJJ rights reserved 
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SPPHRASEELEMENT 



4- 



typedef [restricted] struct SPPHRASEELEMENT 
{ 

ULONG ulAudioStreamOffset; 
ULONG nlAudioTimeOffset; 
ULONG ulAudi oSi zeBytes ; 

ULONG ulAudioSizeTime; //In 100ns units 
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const WCHAR * 
const WCHAR * 
const WCHAR * 
BYTE 
char 
char 
float 
BYTE 
SPPHRASEELEMENT ; 



pszDi splayText ; 
pszLexi calFoinrt'f 
pszPronunciation ; 
bDi splayAttribu tes ; 
RequiredConfi dance ; 
Actual Conf i den ce ; 
SREngineConfidence} 
Reserved; 



Members 

ulAudioStreamOffset 

ulAudioTimeOffset 

ulAudioSizeBytes 

uIAudioSizeTime 

pszDisplayText 

pszLexicalForm 

pszPronunciation 

bDisplay Attributes 

RequiredConfidence 

ActualConfidence 

SREngineConfidence 

Reserved 



© 1995-2 000 Micros oft Corporation A!l rights reserved . 
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SPPHRASEPROPERTY 



Struct SPPHRASEPROPERTY 
{ 

const WCHAR * 
ULONG 

const WCHAR * 

VARIANT 

ULONG 

ULONG 

char 



pszName; 
ulld; 
pszValue; 
vValue; 

ulFirs tEl emen t ; 
ul Court tOfEl emen t £f ; 
Property-Confidence ; 



const SPPHRASEPROPERTY* pNextSibling; 
const SPPHRASEPROPERTY* pFirstChild; 



Members 



pszName 
ulld 

pszValue 
vValue 

Will be VT__BOOL, VTJ4, VT_R4, VT_R8, or VT_B YREF (only for dynamic grammars) 
ulFirstElement 
ulCountOfElements 
PropertyConfidence 
pNextSibling 
pFirstChild 
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SPPHRASEREPLACEMENT 



typedef struct tagSPPHRASEREPLACEMENT 



{ 

BYTE 

const WCHAR * 

XJLONG 

ULONG 

} SPPHRASEREPLACEMENT; 

Members 

bDisplayAttributes 
pszReplacementText 
uIFirstElement 
ulCountOfElements 



bDisplayAttributes ; 
pszReplacementText ; 
uIFirstElement ; 
UlCountOfElements ; 



© 1 995-2000 _Microsoft_Corporation All rightsjeserved 
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SPPHRASERULE 



struct tagSPPHRASERULE 
{ 

const WCHAR * 
ULONG 
ULONG 
ULONG 

const SPPHRASERULE * 
const SPPHRASERULE * 

}; 

Members 



pszName 
uUd 

uIFirstElement 
ulCountOfElements 
pNextSibling 
pFirstChild 

© l?95j:2p00 Micrgsoft Coipprat!^^^ All rights _reser\'ed 
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SPPROPERTYINFO 

SPPROPERTYINFO contains property name and value information. 

typedef struct tagSPPROPERTYINFO 
{ 

const WCHAR *pszNaine; 

ULONG ulld; 

const WCHAR *pszValue; 

VARIANT vValue; 
} SPPROPERTYINFO; 

Members 
pszName 

Pointer to the null-terminated string that contains the name information of the property. 

ulld 

Identifier associated with the property. 
pszValue 

Pointer to the null-terminated string that contains the value information of the property. 
vValue 

Must be one of the following: VT_BOOL, VTJ4, VT_R4, VT_R8, or VT__BYREF (for 
dynamic granmiars only.) 

© 1 995^2000 Microsoft Corporation All rights reserved. 
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SPRECOCONTEXTSTATUS 

typedef [restricted] struct SPRECOCONTEXTSTATUS 

S P INTERFERENCE e Jn t erf erence ; 
WCHAR szReques tTypeOfUI [255] ; 

DWORD dwReservedl ; 

DWORD dwR es erved2 ; 

} SPRECOCONTEXTSTATUS; 

Members 
elnterference 

One of the interference types contained in the SPINTERFERENCE enumeration. 
szRequestTypeOfUI[255] 

Specifies the type of UI requested. If the first byte is NULL, then no UI is requested. 
dwReservedl 

Reserved for future expansion. 
dwReservedl 

Reserved for future expansion. 

© 1995-2000 Microsoft Corporation All rights reserved 
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[This is preliminary documentation and subject to change.] ^ii 

SPRECOGNIZERSTATUS 

typedef [restricted] struct SPRECOGNIZERSTATUS 
{ 

SPAUPIOSTATUS AudioStatus; 

ULONGLONG ullRecogni tionStreamPos; 

ULONG ulStreamNumber; 

ULONG ulNumActive; 

CLSID clsidEngine; 

ULONG cLanglDs ; 

LANGID ahanglDl SPJdAX_LANGIDS J; 

DWORD dwReservedl ; 

DWORD dwReserved2 ; 

} SPRECOGNIZERSTATUS; 

Members 
AudioStatus 

The SPAUDIOSTATUS structure containing the current audio device information. 
uURecognitionStreamPos 
ulStreamNumber 
ulNumActive 

The current engine's number of active languages. 
clsidEngine 

The imique identifier associated with the ciurent engine. 
cLanglDs 

The current engine's number of vaUd language identifiers. 
aLangID 

The engine can support a maximimi of SP_MAX_LANGIDS active languages. 
dwReservedl 

Reserved for future expansion. 
dwReserved2 

Reserved for future expansion. 

© 1 995-2000_Mjcrpsoft Coojoratio^^^ 
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SPRECORESULTINFO 

SPRECORESULTINFO is the resuk structure passed from the engine to SAPL 

typedef struct SPRECORESULTINFO 
{ 

ULONG cbSlze; 

SPRESULTTYPE eResul tType; 

BOOL f Hypothesis; 

BOOL fProprletairyAutoPausej 

ULONGLONG ull StreamPosS tart; 

ULONGLONG ullS treamPosEnd; 

SPGRAMMARHANDLE hGrawmar; 

ULONG ulSi zeEngineDa ta ; 
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void * pvEngineData ; 

ISpPhraseBuilder *pPhrase; 
} SPRECORESULTINFO; 

Members 
cbSize 

Total size, in bytes, of this structure. 
eResultType 

Type of result object (CFG, SLM, or Proprietary). 
fHypothesis 

If TRUE then this recognition is a hypothesis. 
fProprietaryAutoPause 

This field is only used for SPERT_PROPRITARY grammars. If TRUE, the recognition will 

pause. 
uUStreamPosStart 

Starting position within the input stream. 
ullStreamPosEnd 

Ending position within the input stream. 
hGrammar 

Required for SPERT_SLM and SPERT_PROPRIETARY, otherwise this value is NULL 
ulSizeEngineData 

Specifies the size of pvEngineData. 
pvEngineData 

Pointer to the engine data. 
pPhrase 

Pointer to phrase object 

© 1995-2000 Microsoft Coiporali^ A1] rights reserved. 



[This is preliminary documentalion and subject to change.] 

SPRECORESULTTIMES 



SPRECORESULTTIMES contains the time information for speech recognition. This data structure 
is used by the ISpRecoResuit::GetResultTimes method. 



typedef struct SPRECORESULTTIMES 
{ 

FILETIME f tStreamTime 

ULONGLONG ullLength 

DWORD dwTi ckCount ; 

ULONGLONG ul IS tart ; 
} SPRECORESULTTIMES; 

Members 



ftStreamXime 

Number of 100 nanosecond units in UTC time from January 1, 1601 to the start of the current 
result. This is the same as calling the Win32 GetSystemTimeAsFileTimeQ function for the 
result. 
ullLength 

Value containing the length of the phrase specified in 100 nanosecond units. 
dwTickCount 
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Number of 100 nanosecond units clasped from the start of the system to the start of the current 
result. 
ulStart 

Value containing the total 100 nanosecond units from the start of the stream to the start of the 
phrase. 

© 1995-2000 Microsoft Cor pomtion Alirights reserved. 



[This is preliminar}^ documeniation and subject to change.] 

SPRULEENTRY 



typedef [restricted] struct SPRULEENTRY 

SPRULEHANDLE hRulS; 
SPSTATEHANDLE hInitlalState; 



DWORD 
void * 
} SPRULEENTRY; 



Attributes; 
pvCl i en tCon text ; 



Members 
hRule 

hInitialState 

Attributes 

pvClientContext 



© 1995-2000 Microsoft Corporation All rights reserved 
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SPSERIALIZEDEVENT 



typedef [restricted] struct SPSERIALIZEDEVENT 
{ 

WORD eEventId; 
WORD elParamType ; 

ULONG ulStreamNum; 
ULONGLONG ullAudloStreamOffset ; 
ULONG SerlallzedwParam; 
LONG Seri all zedl Param ; 

} SPSERIALIZEDEVENT; 



Members 



eEventId 

One of the event identifiers from the SPEVENTENUM enumeration. 
elParamType 

One of the event parameter types from the SPEyENTLPARA enumeration. 
ulStreamNum 

The input stream number associated with this event. 
ullAudioStreamOffset 
SerializedwParam 



file://C:\WINDOWS\TEMP\~hh4B4E.htm 



12/28/00 



Structures 



Page 14 of 26 



SerializedlParam 



©1995-2000 Microsoft Corporation. Ail ri^iits reserved. 
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SPSERIALIZEDPHRASE 



typedef struct tagSPSERIALIZEDPHRASE 
{ 

ULONG ulSerializedSize ; 

} SPSERIALIZEDPHRASE; 

Members 

ulSerializedSize 

Value specifying the size of the structure in bytes. 



©^1 995-2000 Microsoft Cpiporation.AU rights, reserved 
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SPSERIALIZEDRESULT 



SPSERIALIZEDRESULT contains the phrase size information. 

typedef struct SPSERIALIZEDRESULT 
{ 

UIiONG UlSerializedSize; 
} SPSERIALIZEDRESULT; 

Members 

ulSerializedSize 

The size of the entire phrase in bytes, including this ULONG. 



© 1995-2000 Microsoft .Corporation AIL right_s_resery 
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SPSTATEINFO 



typedef [restricted] struct SPSTATEINFO 

{ 

ULONG cAllocatedEntries ; 

SPTMlNSITIONENTO * pTransitions; 

ULONG cEpsilons; 

ULONG cRules ; 

ULONG cWords ; 
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ULONG cTextBuf fer; 

} SPSTATEINFO; 

Members 

cAUocatedEntries 
pTransitions 

Pointer to a SPTMNSITIONENTRY structure, 
cEpsilons 
cRuIes 
cWords 
cTextBuffer 

©J ?95-200p Microsoft Cprpprgion^AlLn^hts reserved. 
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SPTEXTSELECTIONINFO 



typedef struct tagSPTEXTSELECTlONINFO 
{ 

ULONG ulStartAct iveOf f set ; 

ULONG c chAc t i ve Chars; 

ULONG ulStartSelection; 
ULONG c chS e 1 ec t ion ; 

} SPTEXTSELECTIONINFO ; 

Members 

ulStartActiveOffset 
cchActiveChars 
ulStartSelection 
cchSelection 

© 1 995-2000 MJprosoft Corppration._All righte resen'^^^ 
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SPTMTHREADINFO 

SPTMTHREADINFO contains thread management information implemented by the 
ISpTaskManager interface. 

typedef struct SPTMTHREADINFO 
{ 

long iPoolSize; 
long i Pri ori ty; 
ULONG u I Con cur r en cyLimi t ; 
ULONG ulMaxQul ckAl 1 ocThreads ; 
} SPTMTHREADINFO; 

Members 
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IPoolSize 

Number of threads in pool (-1 default) 
IPriority 

Priority of threads in pool 
ulConcurrencyLimit 

Number of threads allowed to concurrently execute (0 default) 
ulMaxQuickAUocThreads 

Maximum number of dedicated threads retained 



© 1995-2000 MJcrpsotlCorporatio AH rightjjeserved. 
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SPTRANSmONENTRY 

typedef [restricted] struct SPTRANSITIONENTRY 

SPTRANSITIONID ID; 

SPSTATEHANDLE hNextState ; 

BYTE Type; // SPTRANSITIONTYPE 

char RequiredConf idence ; 

struct 

{ 

DWORD fHasProperty; 

//BUGBUG: should be bitfield robch 

}; 

float Weight; 
union 

{ 

struct 

^ SPSTATEHANDLE hRulelnitialState ; // Only if Type == SPTRANSRULE 
SPRULEHANDLE hRule; 
void * pvClientRuleContext; 

}; 

Struct 

SPWORDHAlSrDLE hWord; // Only if Type == SPTRANSWORD 

void * pvClientWordContext ; 

}; 

Struct 

^ void * pvGrammarCookie; // Only if Type == SPTRANSTEXTBUF 

} SPTRANSITIONENTRY; 

Members 
ID 

hNextState 
Type 

RequiredConfidence 

Reserved 

Weight 

hRulelnitialState 
hRule 
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pvClientRuleContext 
hWord 

pvClientWordContext 
pvGrammarCookie 



© 1 995-2000 Microsoft Oarporation Ali _righte reserv'ed 
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SPTRANSITIONPROPERTY 

SPTRANSITIONPROPERTY contains transition property information. 

typedef [restricted] struct SPTRANSITIONPROPERTY 
{ 

const WCHAR *pszNaine; 
ULONG ulld; 
const WCHAR *pszValue; 
VARIANT vValue; 
} SPTRANSITIONPROPERTY; 

Members 
pszName 

Address of a null-terminated string containing the name information. 

ulld 

Identifier associated with the transition property. 
pszValue 

Address of a null-terminated string containing the value information. 
vValue 

For dynamic grammars this value will be VT_BOOL, VTJ4, VT_R4, VT_R8, or 
VT_BYREF. 

© 1995-2000 Microsoft_ Cpippration All rights reserved 

[This is preliminary documentation and subject to change.] ^^JSr 

SPVCONTEXT 

SPVCONTEXT contains information specifying audio string context category information. 

typedef [restricted] struct SPVCONTEXT 
{ 

LPCWSTR pCategory; 
LPCWSTR pBefore] 
LPCWSTR pAfter; 
} SPVCONTEXT; 

Members 
pCategory 

Specifies the name information associated with the context category. 
file://C:\WINDOWS\TEMP\^hh4B4E.htm 12/28/00 
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pBefore 

Specifies the pBefore pointer associated with the audio string. 
pAfter 

Specifies the pAfter pointer associated with the audio string. 

^1^95-2000 Microsoft_^^ A!l rights resented 
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SPVOICESTATUS 

SPVOICESTATUS contains voice stream information. 

typedef struct SPVOICESTATUS 
{ 

ULONG u 1 Cur r en t S tream ; 

ULONG ulLastStreamQueued; 

HRESULT hrLastResul t ; 

DWORD dwRunningState } 

ULONG ul Inpu tWordPos ; 

ULONG ul Inpu tWordLen ; 

ULONG ul Inpu tSen tPos ; 

ULONG ul Inpu tSen tLen ; 

LONG IBookmarkId; 

SPPHONEID Phonemeld; 

SPVISEMES Visemeld; 

DWORD dwReservedl ; 

DWORD dwReserved2 ; 
} SPVOICESTATUS; 

Members 

ulCurrentS tream 

Number of the current stream being synthesized or receiving output. 
UlLastStreamQueued 

Number of the last stream queued. 
hrLastResult 

Result of the last speak. 
dwRunningState 

Set if and only if all streams generated by Speak and SpeakStream calls have been sent to the 
audio output. 
ullnputWordPos 

Character position within the stream of the word currently being rendered. 
ulInputWordLen 

Length of the word currently being rendered. 
ullnputSentPos 

Character position within the stream of the word currently being sent. 
ulInputSentLen 

Length of the word currently being sent. 
IBookmarkId 

Current bookmark name (in base 10) converted to a long integer. If name of current bookmark 

not an integer then IBooJanarkId will be zero. 
Phonemeld 

Current phoneme ID. 
Visemeld 

Ciment viseme ID. 
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dwReservedl 

Reserved for future expansion. 
dwReserved2 

Reserved for future expansion. 



© 1995-2000 Mlcrasgft^prporatlon All jights resented 



[This is preliminary documentation and subject to change.] 

SPVPITCH 



typedef struct SPVPITCH 
{ 

long MiddleAdj ; 
long Range Ad j ; 
} SPVPITCH; 

Members 

MiddleAdj 
RangeAdj 

Remarks 

See Also 



© 1 995-2000 Microsoft .Corj)oration^ AH /isl^ts reserved. 



[This is prelimioaiy documenlaiion and subject to change.^ 

SPVSENTITEM 



typedef struct SPVSENTITEM 



{ 



const SPySTATE* pXmlState; 



LPCWSTR 
ULONG 
ULONG 
ULONG 
} SPVSENTITEM; 



pitem; 
ulItemLen; 

ulltemSrcOf fset ; // Original source character position 
ulItemSrcLen; // Length of original source item in charact 



Members 

pXmlState 

pItem 

uIItemLen 

ulltemSrcOffset 

ulItemSrcLen 



© 1 995-2000 Micrpsoft_Corporatip_n_ All rights reserved. 
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[This is preliminary documentation and subject to change.] 




SPVSTATE 



typedef [restricted] struct SPVSTATE 

// Action 

S PVACT I ONS eAction; 



// Running state values 

LANGID Lang ID; 



WORD wReservedj 



long EmphAdj ; 

long Ra t eAdj ; 

ULONG Volume; 

SPVPITCH Pi tchAdj ; 



ULONG SilenceMSecs ; 

SPPHONEID* pPhonelds; 
SPPARTOFSPEECH ePartOf Speech; 



SPVCONTEXT Context ; 



} SPVSTATE; 

Members 
eAction 

Describes the action to be performed with the associated text fragment. The normal action is to 
Speak (SPVA_Speak) the fragment. 
LangID 

The language ID of the current language. 
wReserved 

Reserved for future use. 
EmphAdj 

Determines if the text should be emphasized. Zero means no emphasis is used and one 
indicates emphasis is used. 
RateAdj 

The current rate for the voice instance. Zero uses the natural rate for the current voice. Other 
values range from -10 to +10. 
Volume 

The current volume level for the voice instance. Valid range is from zero (complete silence) 
through 100 (full natural volume of the current voice). 
PitchAdj 

The current pitch for the voice instance. Zero uses the natural pitch for the current voice. Other 

values range from -10 to +10. 
SilenceMSecs 

The length of a silence, in milliseconds, to be inserted. 
pPhonelds 

Pointer to a null-terminated array of Phone identifiers. 
ePartOfSpeech 

SAPI standard part of speech. 
Context 

The context for the text being synthesized. This is intended for use during the normalization 
phase. A category preceding and following text can be specified. 



© 1 995-2000 Microsoft Corporation. AJLrighte jesprved 
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[This is preliminary documenlaiion and subject to change.] ^0 

SPVTEXTFRAG 

The SPVTEXTFRAG structure contains information about the voice^s text fragment during speech 
synthesis. 

typedef struct SPVTEXTFRAG 
{ 

struct SPVTEXTFRAG* pNext; 
SPVSTATE State; 
LPCWSTR ~ pTextS tart ; 

ULONG ul Tex then ; 

UIiONG ul TextSrcOffset ; 

} SPVTEXTFRAG; 

Members 
pNext 

Pointer to the next text fragment in list. A NULL value indicates the end of the list. 

State 

The current XML attribute state. 
pTextStart 

Pointer to the beginning text string. 
ulTextLen 

The length, in characters, of the text string. 
ulTextSrcOffset 

Original offset position within the text string. 

© 1 995-2000 Microsoft Corporation. Aljji^hts^ reserved. 



[This is preiiminary documentation and subject to change.] 

SPWORD 

SPWORD is used with ISpLexicon to temporarily store the word currently being tested. It is usually 
used in connection with SPWORDLIST. 

typedef [restricted] struct SPWORD 

{ 

struct SPWORD *pNextWord; 

liANGID LangID; 

WORD wRes erved ; 

S PWORDTYPE eVJordType ; 

WCHAR" -^pszJ/^ord} 

S PWORDPRONUNC I AT ION *pFi r s tWordProxmnci at ion } 
} SPWORD; 

Members 

pNextWord 

Pointer to the next word in the list. 
LangID 
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The language ID of the word. 
wReserved 

Reserved for future use. 
eWordType 

Flag of type SPWORDTYPE indicating whether to add or delete the word. 
pszWord 

The offset of the word entry. 
pFirstWordPronunciation 

Pointer to the first possible pronunciation of the word. 

©1995-2000 Microsoft Corporation, All ri^hte reserved. 



[This is preiiminar>'' docinnentaiion and subject to change.] 

SPWORDENTRY 

typedef [restricted] struct SPWORDENTRY 

SPWORDHANDLE hWord; 
LANGID LangID; 

const WCHAR * pszDisplayTextj 

const WCHAR * pszLexicalForm; 

SPPHONEID * aPhoneld; 

void * pvClientContext} 
} SPWORDENTRY; 

Members 

hWord 

Handle to the current word. 
LangID 

Language identifier. 
pszDisplayText 

Pointer to a null-terminated string containing the display text information. 
pszLexicalForm 

Pointer to a null-terminated string containing the lexical text information. 
aPhoneld 

Pointer to a string containing the phoneme identifier. 
pvClientContext 

Pointer to a string representing the cUent context data. 



© 1995-2000 Microsoft Corporation All rights reserved. 



[This is preliminaiy documentation and subject to change.] ^1 

SPWORDLIST 

SPWORDLIST is used with ISpLexicon to set and receive words currently in the lexicon. This 
structure is the beginning of a linked list of SPWORD structures and contains the size and actual 
buffer of all subsequent word operations. 

typedef struct SPWORDLIST 
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{ 

ULONG ulSize; 

BYTE * p vBuf f e r ; 

SPWORD *pFir s tWord ; 
} SPWORDLIST; 

Members 
ulSize 

The size of the buffer for the word, in bytes. 
pvBuffer 

Pointer to the buffer for the word. 
pFirstWord 

Pointer to the first word in the list. 

Examples 

The following example is a code fragment demonstrating the use and creation of SPWORDLIST. The 
code initializes the structure prior to use. 

SPWORDLIST SPWordList; 

hr = ZeroMemory (SiSPWordList, sizeof (SPWordList) ) ; 
if (SUCCEEDED (hr) ) 

hr = pLex->GetWords (eLEXTYPE_USER, &dwGen, &dwCookie, &SPWordList) ; 
: :CoTaskMemFree{ SPWordList. pvBuffer) ; 

© 1995-2000 Microsoft Corporation. All rights resented 

[This is preliminary documentation and subject to change,] 

SPWORDPRONUNCIATION 

SPWORDPRONUNCIATION is used by ISpLexicpn for words with possible variations in 
pronunciation. SPWORDPRONUNCIATION contains the word pronoimcation currently being tried. 



typedef [restricted] struct SPWORDPRONUNCIATION 
{ 

struct SPWORDPRONUNCIATION 

SPLEXICONTYPE 



LANGID 
WORD 

SPPAHTOFSPEECH 
WCHAR 
SPWORDPRONUNCIATION ; 



*pNextWordPronunciati on ; 
eL exi con Typ e ; 
Lang ID 'f 
wReserved; 
ePartOf Speech ; 
szPronunciation [1] ; 



Members 



pNextWordPronunciation 

Pointer to the next possible pronouncation. May be NULL. 
eLexiconType 

Flags of type SPLEXICONTYPE where this pronouncation (PRO)/part of speech (POS) was 

obtained. 
LangID 

The language identifier, 
wReserved 
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Reserved for future use. 
ePartOfSpeech 

The part of speech used by this particular variation, 
szPronunciation [ 1 ] 

The offset from the start of lex file of the sub-lexwordinfoin. Used to convert the part of speech 
or pronouncation to a WORDINFO array. 

© 1995-2000 Microso^^^ 



[This is preliminary documentation and subject to change.] 

SPWORDPRONUNCIATIONLIST 

SPWORDFRONUNCIATIONLIST is used with ISpLexicon::GetPronunciation to list possible 
variations in pronunciation for a given word. It is used to store intermediate values for word 
pronunciations. This structure is the start of a linked list of SPWORDPRONUNCIATION structures 
and contains the size and actual buffer of all subsequent pronunciation attempts. 

typedef struct SPWORDPRONUNCIATIONLIST 

ULONG ulSize; 
BYTE *pvBu ffer; 

SPWORDPRONUNCIATION *pFi rs tWordPronunciati on ; 
} SPWORDPRONONCIATiONLIST; 

Members 
ulSize 

Size of the pronunciation buffer, in bytes. 
pvBuffer 

Pointer to a buffer for one pronunciation. 
pFirstWordPronunciation 

Pointer to a SPWORDPRONUNCIATION structure. 

Example 

The following example is a code fragment demonstrating the use and creation of 
SPWORDPRONUNCIATIONLIST. 

SPWORDPRONUNCIATIONLIST spwordpronlist ; 

memset (spwordpronlist, 0, sizeof (spwordpronlist) ) ; 

pISpLexicon->GetPronunciation(L"resume" , 0, 0, &spwordpronlist) ; 
for ( 

SPWORDPRONUNCIATION pwordpron = pwordpronlist- >pFirstWordPron; 
wordpron != NULL; 

wordpron = pwordpron- >pNextWordPron 
) 

DoSomethingWith (pwordpron- >ePart0f Speech, pwordpron->pszPronIPA) ; 

} 

CoTaskMemFree (spwordpronlist .pvBuffer) ; 

€> 1995-2000 Microsoft Corporation All rights reserved 
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[This is preliminary documentation and subject to change,] IIP 

WAVEFORMATEX 

WAVEFORMATEX defines the format of waveform-audio data. Only format information common 
to all waveform-audio data formats is included in this structure. For formats requiring additional 
information, this structure is included as the first member in another structure, along with the 
additional information. 

typedef [restricted] struct WAVEFORMATEX 
{ 

WORD wFormatTag} 
WORD nChannel s ; 
DWORD nSampl esPerSec ; 
DWORD nAvgBytesPerSec; 
WORD nBl ockAlign ; 
WORD wBi tsPerSampl e ; 
WORD cbSize-f 
} WAVEFORMATEX; 

Members 
wFormatTag 

Waveform-audio format type. Format tags are registered with Microsoft Corporation for many 
compression algorithms. A complete Kst of format tags is located in the Mmsystem.h header 
file. 
nChannels 

Number of channels in the waveform-audio data. Monaural data uses one channel and stereo 
data uses two channels. 
nSamplesFerSec 

Sample rate, in samples per second (hertz), that each channel should be played or recorded. If 
wFormatTag is WAVE_FORMAT_PCM, then conmion values for nSamplesPerSec are 8.0 
kHz, 1 1.025 kHz, 22.05 kHz, and 44.1 kHz. For non-PCM formats, this member must be 
computed according to the manufacturer's specification of the format tag. 
nAvgBytesPerSec 

Required average data-transfer rate, in bytes per second, for the format tag. If wFormatTag is 
WAVE_FORMAT_PCM, nAvgBytesPerSec should be equal to the product of nSamplesPerSec 
and nBIockAIign. For non-PCM formats, this member must be computed according to the 
manufacturer's specification of the format tag. 

Playback and record software can estimate buffer sizes by using the nAvgBytesPerSec member. 
nBlockAlign 

Block alignment, in bytes. The block alignment is the minimum atomic unit of data for the 
wFormatTag format type. If wFormatTag is WAVE__FORMAT_PCM, nBlockAlign should be 
equal to the product of nChannels and wBitsPer Sample divided by 8 (bits per byte). For non- 
PCM formats, this member must be computed according to the manufacturer's specification of 
the format tag. 

Playback and record software must process a multiple of nBlockAlign bytes of data at a time. 
Data written and read from a device must always start at the beginning of a block. For example, 
it is illegal to start playback of PCM data in the middle of a sample (that is, on a non-block- 
aligned boundary). 
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wBitsPerSample 

Bits per sample for the wFormatTag format type. If wFormatTag is WAVE_F0RMAT_PCM5 
then wBitsPerSample should be equal to 8 or 16. For non-PCM formats, this member must be 
set according to the manufacturer's specification of the format tag. Note that some compression 
schemes cannot define a value for wBitsPerSample, so this member can be zero. 
cbSize 

Size, in bytes, of extra format information appended to the end of the WAVEFORMATEX 
structure. This information can be used by non-PCM formats to store extra attributes for the 
wFormatTag. If no extra information is required by the wFormatTag, this member must be set 
to zero. For WAVE_FORMAT_PCM formats only, this member is ignored. 

© 1995-2000 Microsoft Corporation. AU rights reserved 
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Appendix A 



Microsoft Speech SDK 
with SAP! 5.0 




[This is preliminaty documentation and subject to change.] 



Application-Level Interfaces 



This section describes the interfaces and methods for incorporating speech into applications. They are 
intended for use at the API or application level. Some managers or interfaces may have entries also in 
En gine-Level Interface section. However, entries listed here apply only to the application level. 

• Audio Meager 

• Event Manager 

• Grammar Compiler Man ager 

• Lexicon Manager 

• Resource Ms^ager 

• Speech Recognition Ma nag er 

• Text-to-Speech^M 



This section provides SAPI 5.0 audio interfaces. 

Audio inherits from the standard COM IStream interface. See the MSDN documentation for a 
complete discussion of IStream and associated methods. 

• ISpAudio 

• ISpMMSysAudio 

• ISpStream 

• ISpStreamFonnat 

• ISpStreamFgrmatConyerter 

• ISpTranscript 



© 1995-2000 Micro_spft Corporatjpti. All rightsjeseryed 



Microsofl Speech SDK 
with SAPI 5.0 




[This is preiiminar\^ documentation and subject to change.] 



Audio interfaces 



©1995-2000 Microsoft Corporation All rights reser\;ed 



Microsoft Speech SDK 
with SAPI 5.0 




[ITiis is prcjiminar>^ docmnentation and subject to change] 



ISpAudio 
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When to Implement 

Objects implementing this interface are real-time audio streams, such as those connected to a live 
microphone or telephone line. ISpAudio methods allow control over the real-time behavior of the 
stream. IStream Read and Write methods transfer data to or from an object. 

Note: The ISpAudio interface inherits from ISpStoearnFormat. 

Methods in Vtable Order 

ISpAudio Methods Description 

SetState Sets the state of the audio device. 

SetFormat Sets the format of the audio device. 

GetStatus Passes back the status of the audio device. 

SetBufferlnfo Sets the audio stream buffer information. 

GetBufferlnfo Passes back the audio stream buffer information. 

GetDefaultFormat Passes back the default audio format. 

EventHandle Retums a Win32 event handle that appUcations can use to 

wait for status changes in the I/O stream. 

GetVoIumeLevel Passes back the current volume level. 

SetVoIumeLevel Sets the current volume level. 

GetBufferNotifySize Retrieves the audio stream buffer size information. 

SetBufferNotifySize Sets the audio stream buffer size information. 

©1995-2000 Microsoft Coa)oration._An^r^^^^ 



[This is preliminary^ documentation and subject to change.] IS? 

ISpAudio: : SetState 

ISpAudio::SetState sets the state of the audio device. 

When transitioning from the SPAS^CLOSED state to any other state, the caller should be ready to 
handle various error conditions, specifically, SPERR_„FORMAT^NOT_SUPPORTED and 
SPERR_DEVICE_BUSY. Many multi-media devices do not correctly report their capabilities for 
handling different audio formats and fail only when an attempt is made to open the device. 

Also, in many older systems, audio output devices can only be opened by a single process. In all 
current versions of Windows, only a single process can open an audio input device. Therefore, 
SPERR_DEVICE_BUS Y will return if an attempt is made to open a device that is being used by a 
different process or thread. 

HRESULT SetState ( 

SPAUDIOSTATE NewState, 
ULONGLONG ul iReserved 

); 
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Parameters 

NewState 

[in] The flag of type SPAUDIOSTATE for the new state of the audio device. 
uIlReserved 

[in] Reserved, do not use. This value must be zero. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_rN VALIDARG ullReserved is not zero. 

SPERR_DEVICE_BUS Y Hardware device is in use by another thread or process. 

SPERR_FORMAT_NOT_SUPPORTED Current format set by ISpAudio:;SetFonnat is not 

supported by the hardware device. 

P. } ?95-_2p00 Microsoft Coiporatioa, AI I rights reserved 

[This is preliminar>^ documentation and subject to change.] 1^ 

ISpAudio::SetFormat 

ISpAudio::SetFormat sets the format of the audio device. 

This method can only be called when the audio device is in the SPAS^CLOSED state. Note that 
successftiUy setting the format on a audio device does not necessarily mean the format is supported. 
An attempt must be made to place the device into a non-closed state (SPAS_STOP, SPAS_PAUSE 
or SPAS_RUN) to be sure that the device can handle the format. 

The format can be retrieved by calling the ISpStreaniFormat: i^GetFormat method. 

HRESULT SetFonnat( 

REFGUID rguidFmtId, 

cons t WAVEFORMATEX -^pWav^eForma tEx 

) ; 

Parameters 

rguidFmtId 

[in] The REFGUID for the format to set. 
p WaveFormatEx 

[in] Address of the WAVEFORM structure containing the wave file format information. 
Return values 
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Value Description 

S_OK Fimction completed successfully. See note about 

supported formats. 

E_I]SI VALID ARG pWaveFormatEx is invalid or bad. 

SPERR_DEVICE_BUSY Device is not in the SPAS_CLOSED state. 

SPERR_UNINITI ALIZED Audio stream not initialized. 

SPERR_FORMAT_NOT_SUPPORTED Specified format is not supported. 
FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation. All rights res_erved. 

[This is preliminar}-' documentation and subject to change.] 

ISpAudio: :GetStatus 

ISpAudio::GetStatus gets the status of the audio device. 

Use this method to determine whether the device is running, stopped, closed, or paused. It also 
determines the size of any buffered data. 

HRESULT GetStatusC 

SPAUDI OS TATUS *pS ta t u s 

); 

Parameters 

pStatus 

[out] Pointer to the SPAUDIOSTATUS buffer. 
Return values 

Value Description 

S_OK Function completed successfully. 

E^POINTER pStatus is invalid. 

© 1995-2000 Micros_oft_Corporatipn. All rights reser\'ed 



[This is preliminary documentation and subject to change.] 

ISpAudio: :SetBufferInfo 

ISpAudio: rSetBufferlnfo sets the audio stream buffer information. 

This method can be called only when the audio device is in the SPAS CLOSED state. The 
SPAUDIOBUFFERINFO members must conform to the following restrictions: 
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SPAudioBufferlnfo.ulMsMinNotification may be at most one quarter the size of 
SPAudioBufferlnfo.ulMsBufferSize. 

SPAudioBufferlnfo.ulMsEventBias can be no larger than SPAudioBufferlnfo.ulMsBufferSize. 

HRESULT SetBufferInfo( 

const SPAUDIOBUFFERINFO *pBuffInfo 

); 

Parameters 

pBufflnfo 

[in] Pointer to the SPAUDIOBUFFERINFO buffer. 
Return values 

Value Description 

S OK Function completed successfully. 

SPERR^UNINITIALIZED Audio stream not initialized. 

E_rN VALID ARG pBufflnfo is invalid or the parameters do not meet the 

criteria described above. Altemaltely 

SPERR_DEVICE_BUS Y Audio device is not in the SPAS_CLOSED state. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation. All rights reserved 



[This is preliminary' documentation and subject to change.] 

ISp Audio : : GetBuf f erinf o 

ISpAudiorrGetBufferlnfo gets the audio stream buffer information. 

HRESULT GetBuf ferInfo( 

SPAUDIOBUFFERINFO *pBuffInfo 

) ; 

Parameters 

pBufflnfo 

[out] Pointer to the SPAUDIOBUFFERINFO buffer. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_POINTER pBufflnfo is invalid. 

© 1995:2000 Microsoft Coiporatipn. All righte reserved. 
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[This is preliminaiy documentation and subject to change] 




ISpAudio: :GetDefaultForinat 



ISpAudio::GetDefaultFormat gets the default audio format. 



Other formats may be supported by the audio device; this format is guaranteed to work. 



HRESULT GetDefaultFormat ( 

QUID *pFoxmatId, 



WAVE FORMATEX * *ppCoMemWave Forma tEx 

) ; 

Parameters 

pFormatId 

[out] Pointer to the GUID of the default format. 
ppCoMem WaveFormatEx 

[out] Address of a pointer to the WAVEFORMATEX structure that receives the wave file 
format information. 

Return values 



Value Description 

S_OK Function completed successfully. 



ISpAudio ::EventHandle returns a Win32 event handle that applications can use to wait for status 
changes in the I/O stream. 

The handle may use one of the various Win32 wait functions, such as WaitForSingleObject or 
WaitForMultipleObjects. 

For read streams, set the event when there is data available to read and reset it whenever there is no 
available data. For write streams, set the event when all of the data has been written to the device, and 
reset it at any time when there is still data available to be played. 

The caller should not close the returned handle, nor should the caller ever use the event handle after 
calling ReleaseQ on the audio object. The audio device will close the handle on the final release of 



SPERR_UNINITIALIZED 

E_POrNTER 

E POINTER 



Stream is uninitialized. 

At least one of pFormatId or pFormatId is invalid or bad. 
pFormatId is invalid. 



©1995-2000 Microsoft _Cqrporatioii All righ^ reserved. 
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ISpAudio: :EventHandle 
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the object. 

HANDLE EventHandle ( void ) ; 
Parameters 

None 

Return values 

Value Description 

HANDLE Returns valid event handle. 



ISpAudio::GetVolumeLevel passes back the current volume level. 
The volume level is on a linear scale from 0 to 10000. 

HRESULT GetVoliimeLevel ( 
ULONG *pLevel 

); 

Parameters 

pLevel 

[out] Pointer to the returned volume level. 
Return values 

Value Description 

S_OK Function completed successfully. 

SPERR__UNINITIALIZED Audio interface is not initialized. 

SPERR_DEVICE__NOT_SUPPORTED The device is not valid or does not support volumes. 
E_POINTER pulLevel is invalid or bad. 

E INVALIDARG The argument is invalid or is not the correct size. 

FAILED(hr) Appropriate error message. 



© 1995-2000 Microsoft Corporation Al! rights resented 
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ISp Audio : : GetVolumeLevel 
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ISp Audio : : SetVolumeLevel 



ISpAudio::SetVolumeLeveI sets the current volume level 
It is on a linear scale from 0 to 10000, 

HRESULT SetVolojineLevel ( 
ULONG Level 

); 

Parameters 

Level 

[in] The new volume level. 
Return values 

Value Description 

S_OK Function completed successfully. 



ISpAudio::GetBufferNotifySize retrieves the audio stream buffer size information. This information 
is used to determine when the event returned by ISpAudio::EyentHandle is set or reset. 

For read streams, the event is set if the audio buffered is greater than or equal to the value set in 
pcbSize, otherwise the event information is reset. 

For write streams, the event is set if the audio buffered is less than the value set in pcbSize, otherwise 
the event information is reset. 

HRESULT GetBuf f erNotifySize ( 
ULONG *pcbSize 

); 



[out] Address of the size information, specified in bytes, that is associated with the audio 
stream buffer. 



©1995:2000 Microsoft Con)oratjpji_Anrighte reserved 
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ISpAudio: :GetBufferNotifySize 



Parameters 



pcbSize 



Return values 
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Value 

S^OK 

E^INVALIDARG 

E_POINTER 

FAILED(hr) 



Description 

Function completed successfully. 
One or more arguments are invalid. 
Invalid pointer. 
Appropriate error message. 



© 1995-2000 Microsoft Corporation AM rights reserved . 
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ISp Audio : : SetBufferNotify Size 



ISpAudio::SetBufferNotifySize sets the audio stream buffer size information. This information is 
used to determine when the event retumed by ISpAudio::EventHandle is set or reset. 

For read streams the event is set if the audio buffered is greater than or equal to the value set in 
pcbSize, otherwise the event information is reset. 

For write streams the event is set if the audio buffered is less than the value set in pcbSize, otherwise 
the event information is reset. 

HRESULT SetBufferNotifySize( 
ULONG cbSize 

); 

Parameters 

cbSize 

[in] The size, specified in bytes, of the information associated with the audio stream buffer. 
Return values 

Value Description 

S_OK Function completed successfully. 

FAILED(hr) Appropriate error message. 



© 1 995-2000 Microsoft Corporation All rights reserved . 



Microsoft Speech SDK 
with SAPI 5.0 




[This is preliminary documentation and subject to change.] 



ISpMMSysAudio 



ISpMMSysAudio inherits from ISpAudio. 
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This is the interface to the audio implementation for the standard Windows multimedia layer (wave 
in and wave out). Audio objects created through an object token do not allow the 
I S p M MSysAudio::SetDeviceId method to work because the token specifies which audio device ID to 
use. If, for some reason an application wants to associate an audio object with a specific multimedia 
wave in or wave out device ID, it should use CoCreatelnstance with CLSID_SpMMAudioOut or 
CLSID_SpMMAudioIn and then use the SetDeviceld method to select the desired device. 

Methods in Vtable Order 



ISpMMSysAudio Methods Description 

GetDeviceld Passes back the multimedia device ID being used by the 

audio object. 

SetDe viceld Sets the multimedia device ID. 

GetMMHandle Passes back a multimedia audio stream handle. 

©. 1 Microsoft Con'oration._An righbjeseryed. 



[This is preliminary documentation and subject to change-] ^iP 

ISpMMSysAudio: :GetDeviceId 

ISpMMSysAudio::GetDeviceId passes back the multimedia device ID being used by the audio 
object. 

Initially set this device ID to WAVE_MAPPER for instances of CLSID_SpMMAudioIn or 
CLSID SpMMAudioOut, which were created using CoCreatelnstance. For audio objects created 
using an object token, the ID will always be a specific wave in or wave out device ID. 

HRESULT GetDeviceld ( 
UINT *puDeviceId 

); 

Parameters 

puDeviceld 

[out] Pointer receiving the device ID. 

Return values 

Value Description 

S_OK Function completed successfully. 

E_POINTER puDeviceld is invalid. 

©1995-2000 Microsoft Corppratipn All rights_reserved 



[This is preliminarv'- docimieiilaiion and subject to change. 
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ISpMMSysAudio::SetDeviceId 

ISpMMSysAudio::SetDeviceId sets the multimedia device ID. 

This method works only on audio objects that were not created using an object token, and only when 
the object is in the SPAS_CLOSED state. 

HRESULT SetDeviceId{ 
UINT uDeviceld 

); 

Parameters 

uDeviceld 

[in] The device ID of the device to set. 

Return values 

Value Description 

S_OK Function completed successfully. 

SPERR_DEVICE_BUSY Object is not in the SPAS_CLOSED state. 

SPERR_ALREADY_INITIALIZED Object was created using an object token. 

E_IN VALIDARG uDeviceld is invahd. It is not set to WAVE_MAPPER or 

device does not exist. 

©_19p5-200p_Micrpsptl Corporation All rights reserved. 



[This is preliminary documentation and subject to change.] ^Sl 

ISpMMSysAudio: :GetMMHandle 

ISpMMSysAudio::GetMMHandle passes back a multimedia audio devicestream handle. 

The audio object must not be in the SPAS_CLOSED state or this call will fail because the 
multimedia device will not have been opened yet. The caller must not close the passed back handle. 
The caller must not use the handle either after changing the state of the audio object to 
SPAS_CLOSED or after releasing the object. 

HRESULT GetMMHandle( 

vo i d * *pHandl e 

); 

Parameters 

pHandle 

The wave in or wave out device handle. 
Return values 
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Value 

S_OK 

E_POINTER 

SPERR UNINITIALIZED 



Microsoft Speech SDK 
with SAPI 5.0 



Description 

Function completed successfully. 
pHandle is invalid. 

Audio object is in the SPAS_CLOSED state. 



© 1995-2000 Microsoft Corporation M reserved. 



[This is preliminary documentation and subject to change,] 



ISpStream 



Note: This interface inherits from ISpStreamForniat. 
Methods in Vtable Order 



ISpStream Methods 

SetBaseStream 

GetBaseStream 

BindToFile 

Close 



Description 

Sets the base address of the audio stream. 
Retrieves the base address of the audio stream. 
Binds the audio stream to the file that it identifies. 
Closes the audio stream. 

© 1 995-2000_ Microsoft Coiporatiqri^Aj ^ Jights reserved. 



[This is preliminary documentation and subject to change.] IS 

ISpStream::SetBaseStream 

ISpStream:: SetBaseStream sets the base address of the audio stream. 

HRESULT SetBaseStream ( 

I S t r e am *p5 tream , 

REFGUID rgnidForma. t , 

const WAVEFORMATEX *pWaveFormatEx 

); 

Parameters 

pStream 

Address of the IStream containing the base audio stream data. 
rguidFormat 

Address of the data format identifier associated with the audio stream. 
p WaveFormatEx 

Address of the WAVEFORMATEX structure that contains the wave file format information. 
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Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG One or more arguments are invalid. 

SPERR_UNINITIALIZED The object has not been properly initialized. 

SPERR_^ALREADY_INITIALIZED The object has already been initialized. 



© 1995-2000_Mi_crpsoft Corporation All rights resented 



[This is preliminary documentation and subject to change,] 

ISpStream : : GetBaseStream 

ISpStream::GetBaseStream retrieves the base address of the audio stream. 

HRESULT GetBaseStream ( 
IStream **ppStream 

); 

Parameters 

ppStream 

Address of a pointer to the IStream that contains the audio stream. 
Return values 

Value Description 

S_OK Function completed successfully, 

E_POINTER Invalid pointer. 

© 1 995-2000 Microsoft CoiporatioTi._All rights reservied 



[This is preliminai)'^ documentation and subject to change,] 

ISpStream : :BindToFile 

ISpStream: :BindToFile binds the audio stream to the file that it identifies. 

HRESXJLT BindToFile( 

const WCHAR -^pszEileName , 

SPFILEMODE eMode , 

const GUlb *pFonnatId, 

const WAVEFORMATEX -^pWaveFormatEx , 

ULONGLONG ul lEven tin teres t 

); 
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Parameters 

pszFileName 

Address of a null-terminated string containing the file name. 
eMode 

Flags of the type SPFILEMODE for the desired file mode. 

When opening an audio wav file, specify the mode SPFM_OPEN_READONL Y or 
SPFM_CREATE_ALWAYS, otherwise the other modes will fail. 

pFormatId 

Address of the data format identifier associated with the stream. 
p WaveFormatEx 

Address of the WAVEFORMATEX structure that contains the wave file format information. 

tillEvQyitlTltCTCSt 

Flags of type SPEVENTENUM for the desired events. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_IN VALID ARG One or more arguments are invalid. 

SPERR_ALREADY_INITIALIZED The object has already been initialized. 



ISpStream::Close closes the audio stream. Use this to vaUdate the close operation. 

HRESULT Close ( void ) ; 

Parameters 

None. 

Return values 

Value Description 

S_OK Function completed successfully. 

FAILED (hr) Appropriate error message. 



© J_995-200p^Micros(>ft Corporation Ail rights, reserved 



[This is preliminary documenlaiion and subject to change, j 




ISp Stream : : Close 



© 1995-2000 Microsoft CorporatipiL All rightsreserved. 



Microsoft Speech SDK 
with SAPI 5.0 




file://C:\WIND0WS\TEMP\~hh2B lB.htm 



12/28/00 



Application-Level Interfaces 



Page 15 of 199 



[This is preliminaiy docimientation and subject to change,] 



ISpStreamFormat 



ISpStreamFormat inherits from IStream. 



Methods in Vtable Order 



ISpStreamFormat Methods 
GetFormat 



Description 

Passes back the cached format of the stream. 



©i?95-2000 Microsoft Corporation All rights reserved 



[This is preliminary^ documentation and subject to change.] 




ISpStreamFormat: : GetFormat 



ISpStreamFormat:: GetFormat passes back the cached format of the stream. 



HRESULT GetFormat { 
QUID 



*pgui dForma tid. 



WAVEFORMATEX * ^ppCoMemWaveFouna tEx 

); 

Parameters 

pguidFormatId 

The actual format of the stream being used. 
ppCoMem WaveFormatEx 

Address of a pointer to a WAVEFORMATEX data structure that contains the wave file format 

information. 

Return values 

Value Description 

S_OK Function completed successfully. 



© 1 995-2000 Microsoft Corporation .All_ rights reserved. 
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[This is preliminary documentation and subject to change.] 



ISpStreamFormatConverter 
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ISpStreamFormatConverter inherits from ISpStreamFomiat. Several methods are included to allow 
data conversion. 

Methods in Vtable Order 



ISpStreamFormatConverter Methods Description 



SetBaseStream 

Ge tBaseStream 

S etFo rmat 

Re setSeekPosition 

ScaleConvertedToBaseOffset 



ScaleBaseToConvertedOffset 



Sets the current audio stream. 

Gets the current audio stream. 

Sets the base stream format. 

Resets the seek position to the start of the stream. 

Converts a stream offset in the converted stream into a 
stream offset in the base stream. 

Converts an offset in the base stream into a stream offset 
in the converted stream. 



© 1995-2000 Microsoft Corporation. All rights resented 



[This is preliminary documentation and subject to change.] 



ISpStreamFormatConverter: : SetBaseStream 

ISpStreamFormatConverter:: SetBaseStream sets the current, or base audio stream. 

HRESULT SetBaseStream ( 

ISpStreatnFormat *pStream, 

BOOL fSetFoirmatToBaseStreamFormat, 
BOOL fWri teToBaseStream 

); 

Parameters 

pStream 

[in] Address of an ISpStreamFormat containing the base audio stream data. 
JSetFormatToBaseStreamFormat 

[in] Flag specifies that the stream will be set to the same format as the base stream. 

If TRUE, then format of format converter stream will be set to same format as base stream (set 
up as a pass-through). If pStream == NULL and this is set to TRUE, then format of stream is 
reset. 

JWriteToBaseStream 

[in] Flag specifies that the steam will be written to the base stream. 



Return values 
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Value Description 

S_OK Function completed successfully. 

FAILED (hr) Appropriate error message. 

© 1 995:2000 Microsoft Corporation. Alj rights reserved. 



[This is preliminary documentation and subject to change.] 1^ 

ISpStreamFormatConverter::GetBaseStream 

ISpStreamForinatConverter::GetBaseStream gets the current audio stream. 

This parameter can be NULL if that information is not required. Use this method to simply test if 
there is a stream by calling it and checking for a retum code of S_FALSE. 

HRESULT 6etBaseStream( 

ISpStreamFormat **ppStream 

); 

Parameters 

ppStream 

[out] The current base audio stream. 

Return values 



Value Description 

S_OK Fimction completed successfully. 

S FALSE No base stream is present. 

E_POINTER Pointer is bad or invalid. 

FAILED (hr) Appropriate error message. 



Ll??5-20()0 MicrosoA Corporation M rights reserved 



[This is preliminary documentation and subject to change.] -'WS 

ISpStreamFormatConverter::SetFormat 

ISpStreamFormatConverter::SetForniat sets the base stream format. 

HRESULT SetFormat ( 

REFGUID rgui dFoima tIdOf Convert edS tream, 

const WAVEFORMATEX *pNaveFo2nnatExOfConvertedStream 

); 

Parameters 
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rguidFormatldOfConvertedStream 

[in] Address of the data format identifier associated with the converted stream. 
p WaveFormatExOfConvertedStream 

[in] Address of the WAVEFORMATEX structure containing the wave file format information 

of the converted stream. 

Return values 

Value Description 

S_OK Function completed successfully. 

FAILED (hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation. Aii rights resented 

[This is preliminary documentation and subject to change.] ^S^' 

ISpStreamFormatConverter::ResetSeekPosition 

ISpStreamFormatConverter::ResetSeekPosition resets the seek position to the start of the stream. 

HRESULT ResetSeekPosition( void ); 
Parameters 

None. 

Return values 

Value Description 

S_OK Function completed successfully. 

SPERR_UNINITIALIZED Current stream base is uninitiaUzed. 

FAILED (hr) Appropriate error message. 

© 1?95-2000 Micrpsoft Corppration. All rights 

[This is preliminary^ documentation and subject to change.) 

ISpStreamFormatConverter::ScaleConvertedT 

ISpStreamFormatConverterriScaleConvertedToBaseOffset converts a stream offset in the 
converted stream into an offset in the base stream. 

HRESULT ScaleConvertedToBaseOf f set { 

ULONGLONG nil Offse t ConvertedS tream , 
ULONGLONG -^pullOffsetBaseStream 

) ; 
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Parameters 

ullOffsetConvertedStream 

The offset of the current stream. 
pullOffsetBaseStream 

The new offset in the base stream. 

Return values 

Value Description 

S_OK Function completed successfully. 

E_POINTER pullConvertedOffset is invalid. 

SPERR__UNINITIALIZED SetBaseStream has not been called successfully. 

FAILED (hr) Appropriate error message. 

© )995-2000 Microsoft Corporatjoti AH rights resen/ed. 



[ITiis is preliminary documentation and subject to change, j 

ISpStreamFormatConverter::ScaleBaseToConv 

ISpStreamFormatConverter::ScaleBaseToConvertedOffset converts an offset in the base stream 
into an offset in the converted stream. 

HRESULT ScaleBaseToConvertedOf f set ( 
ULONGLONG nil Offs e tBa s eS tream , 
ULONGLONG *piil I Of fsetConvertedS tream 

); 

Parameters 

ullOffsetBaseStream 

The current offset in the base stream. 
pullOffsetConvertedStream 

The new offset in the converted stream. 

Return values 

Value Description 

S OK Function completed successfully. 

E POINTER pullOffsetConvertedStream is bad or invalid. 

SPERR_UNINITIALIZED ullOffsetBaseStream is less than the initial seek position of 

the current steam. "^pullOffsetConvertedStream is set to 
OxFFFFFFFFFFFFFFFF. 

SPERR_UNINITIALIZED SetBaseStream has not been called successfully. 

FAILED (hr) Appropriate error message. 
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© 1995-2000 Microsoft.Corporatipn. All rights. reserved 



Microsoft Speech SDK 
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[This is preliminaty documentation and subject to change.] 



ISpTranscript 



Methods in Viable Order 



ISpTranscript Methods 

GetT ranscript 

Ap pen dTranscript 



Description 

Gets the current transcript. 

Adds the current text to the transcript. 



© 1995-2000 Microsoft_Corporatipn AU rights reserved 



[This is preliminary documentation and subject to change.] 

ISpTranscript: : GetTranscript 

ISpTranscript:: GetTranscript gets the current transcript. 

HRESXJLT GetTranscript { 

WCHAR **ppszTranscript 

); 



Parameters 

ppszTranscript 

[out, string] A pointer to the transcription string. 

Return values 



Value 

S_OK 

E_INVALIDARG 

E_OUTOFMEMORY 

SPERR_UNINITIALIZED 

E_POE^iTER 

S_FALSE 

FAILED (hr) 



Description 

Function completed suco^ssMiy. ppszTranscript contains 
a CoTaskMemAUocated string. 

ppszTranscript is bad or invalid. 

Exceeded available memory. 

Object has not been initialized. 

ppszTranscript is bad or invalid. 

No transcript is present. 

Appropriate error message. 



Example 
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HRESULT hr = S_OK; 
CComPtr<IStreaTn> cpWavStream; 

hr = SPOpenWavFile{L"Created.Wav", NULL, &cpWavStream) ; 
CComQIPtr<ISpTranscript> cpTrans (cpWavStream) ; 
CSpDynamicString dstrTranscript ; 
cpTrans->GetTranscript (&dstrTranscript) ; 
WCHAR * psz = dstrTranscript; 

pVoice->SetInterest (SPFEI_WORDBOUNDARY | SPFEI_END_INPUT_STREAM, 0) ; 
hr = pVoice->SpeakStream (cpWavStream, NULL, 0, SPF_ASYNC, NULL) ; 

while (TRUE) 
{ 

SPVOICESTATUS Stat; 

pVoice->WaitForNotifyEvent (INFINITE) ; 

pVoice->GetStatus (&Stat, NULL) ; 

if (Stat .dwRunningState & SPRS_DONE) break; 

while (static cast <ULONG> (psz - dstrTranscript) < (Stat .ullnputWordPos + S 
{ 

wprintf (L"%lc" , *psz++) ; 



//Print the remainder (if any) 
wprintf (L"%s\n" , psz) ; 
pVoice->SetNotifySink(NULL) ; 

©J?_95r2Q00 Micrpsoft^Corpprat^^^^ AH rights reserved. 



^^^^^ 



[This is preliminai7 docimientation and subject to change,] 

ISpTranscript: : AppendTranscript 

ISpTranscript::AppendTranscript adds the current text to the transcript. 

HRESULT AppendTranscript ( 

const WCHAR *pszTranscript 

); 

Parameters 

pszTranscript 

[in, string] The text of the transcript. If pszTranscript is NULL, then the current transcript is 
deleted. Otherwise, the text is appended to the current transcript. 

Return values 

Value Description 

S OK Function completed successfully. 

E_INVALIDARG pszTranscript is bad or invalid. 

E_OUTOFMEMORY Exceeded available memory. 

FAILED (hr) Appropriate error message. 
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Example 



HRESULT hr; 

CComPtr<IStreaTn> cpWavStream; 

// Wrapper for ISpWavStream: : Create 

hr =: SPCreateWavFile (L" Created. Wav" , SPDFID_22kHzl6BitMono, SicpWavStream) ; 
if (SUCCEEDED (hr) ) 

hr = pVoice->SetOutput (cpWavStream, NULL); 
CComQIPtr<ISpTranscript> cpTrans (cpWavStream) ; 

cpTrans->AppendTranscript {L"This is a simple sample sentence"); 
if (SUCCEEDED (hr) ) 



//A sample of generated speech written to a WAV file 

hr = pVoice->Speak( L"This is a simple sample sentence.", 0, 0, NULL) ; 
pVoice->SetOutput (NULL, NULL) ; 



//Start the media player on the created file 

pVoice->Speak( L"Press the play button to play the recorded audio.", 0, 0, NUL 
cpWavStream. Release 0 ; 
if ( SUCCEEDED (hr) ) 

^ : :ShellExecute(NULL, "open", _T { "Created. Wav" ) , NULL, NULL, SW__SHOWNORMAL) 



This section provides SAPI 5.0 event information. 

• ISpNotifySource 

• ISpNotifyS 

• ISpNoti^^Translato 

• ISpEventSink 

• ISpEventSource 

• ISj)Noti^Cal_lback 



€> 1995-2000 Microsoft Corporation. All rights reserved 
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This is preliminary documentation and subject to change. ) 



Eventing interfaces 
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ISpNotifySource 
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In both speech synthesis and speech recognition, applications receive notifications when words have 
been spoken or when phrases have been recognized. SAPI components that generate notifications 
implement an ISpNotifySource. 

The ISpNotifySource and ISpNoti^Sink interfaces by themselves only provide a mechanism for a 
notification but no information on the events that caused the notification. With an ISpEventSource 
object, an application can retrieve information about the events that caused the notification. An 
ISpEventSource also provides the mechanism to filter and queue events. By default, an application 
(really an ISpNotifySink) receives no notifications firom ISpEventSource until Setlnterests has been 
called to specify on which events to notify or queue. 

When an application is notified of an event that is not queued, an application will take measures 
based on which event sink receives the notification. From context, an apphcation might know exactly 
what it needs to do, or it may need to interact with the components which sent the notifications. If an 
application is notified of an event which is queued, then the application will call 
ISpEventSource ::GetEvents to retrieve the actual events that caused a notification. 

When to Implement 

Implement the ISpNotifySource interface dxiring initialization to set the default action for how an 
event source notifies the receiver. 

Methods in Vtable Order 

ISpNotifySource Methods Description 

SetNotifySink Sets up the instance to make free-threaded calls through 

ISpNotifySink: :Notify. 

SetNotifyWindowMessage Sets a window callback function to receive notifications as 

window messages. 

SetNotifi^CalibackFunction Sets a callback function to receive notifications. 



_ 



SetNotifyCalibacMn^^^ Enables an object derived from ISpTask to receive 

notifications. 

SetNotifyWin32Eveiit Sets up a Win32 event object to be used by this instance. 

WaitForNotifyEvent A blocking call in response to a SAPI notification event. 

GetNotifyE>entHa^ Retrieves notifications via Win32 events. 

© 1995-2000 Microsoft Corporation All rights reserved 



[This is preiiminaiy documentation and subject to change.] 

ISpNotifySource: rSetNotifySink 

ISpNotifySource::SetNotifySink sets up the instance to make free-threaded calls through 
ISENpti.fySink.::Notify. 

HRESULT SetNotifySink ( 

ISpNotifySink *pNotifySink 

); 
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Parameters 

pNotifySink 

[in] Pointer to the notification method. May be NULL if no default action is required. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_F AIL Interface not initialized. 

FAILED (hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation All rights resented 



[This is preliminaiy documentation and subject to change.] 

ISpNotify Source : : SetNotifyWindo wMessage 

ISpNotifySource::SetNotifyWindowMessage sets up the instance to send window messages to a 
specified window. 

HRESULT SetNotifyWindowMessage { 
HWND hWnd, 
UINT Msg, 
WPARAM wParam , 
LPARAM IParam 

); 

Parameters 

hWnd 

[in] Handle to the window whose message handler function will receive SAPI notifications. 

Msg 

[in] Message number which will be passed into the message handler function of the window 
hWnd. 
wParam 

[in] wParam that will be passed into the message handler fonction of the window hWnd. 
IParam 

[in] IParam that will be passed into the message handler function of the window hWnd, 
Return values 

Value Description 

S_OK Function completed successfully. 

E_FA[L Interface not initialized. 

FAILED (hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation. All rights reserved . 
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[This is preiiminary documentation and subject to change,] 

ISpNotifySource::SetNotifyCallbackFunction 

ISpNotifySourcerrSetNotifyCallbackFunction sets up this instance to send notifications via a 
standard C-style callback function. 

HRESULT SetNotifyCallbackFunction ( 
SPNOTIFYCALLBACK *pfnCallback, 
WPARAM wParam, 
LPARAM 1 Par am 

); 

Parameters 

pfnCallback 

[in] The notification callback fimction to be used. 
wParam 

[in] Constant word value that will be passed to the pfnCallback function when it is called. 
IParam 

[in] Constant long value that will be passed to the pfnCallback function when it is called. 
Return values 

Value Description 

S_OK Function completed successfully. 

E FAIL Interface not initialized. 

FAILED (hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation, AU_ rights reserved. 



[Tills is preliminary- documentation and subject to change.] iSPf 

ISpNotifySource::SetNotifyCallbackInterface 

ISpNotifySource::SetNotifyCallbackInterface sets up this instance to call the virtual method 
ISpNotifyCallback: :Notify^Callback for notifications. 

HRESULT SetNotifyCallbacklnterf ace ( 

ISpNotifyCallback *pSpCallback , 
WPARAM wParam, 
LPARAM IParam 

); 

Parameters 

pSpCallback 

[in] A pointer to an application-defined implementation of the ISpNotifyCallback interface. 
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wParam 

[in] Constant word value that will be passed to the NotifyCallback method when it is called. 
IParam 

[in] Constant long value that will be passed to the NotifyCallback method when it is called. 
Return values 

Value Description 

S__OK Fxmction completed successfully. 

E_FAIL Interface not initialized. 

FAILED (hr) Appropriate error message. 

© J 995-2000 Micjosoft Corporation. AUrights reserved 

[This is preliminary documentation and subject to change.] 

ISpNotifySource::SetNotifyWin32Event 

ISpNotifySource::SetNotifyWin32Event sets up a Win32 event object to be used by this instance. 

For an explanation of Win32 event objects, see the Win32 Platform SDK documentation. Once an 
event object has been initialized for this instance, use either the WaitForNotify Event and 
GetNotfyEventHandle methods. Note that Win32 event objects and SAPI events are different 
notifications. 

HRESULT SetNotifyWin32Event ( void ) ; 

Parameters 

None 

Return values 

Value Description 

S_OK Function completed successfully. 

E FAIL Interface not initialized. 

FAILED (hr) Appropriate error message. 

©_l995:2pp0 Microsoft Corppmlipn„. All rights reserved 



[This is preliminaiy documentation and subject to change.] 

ISpNotifySource::WaitForNotifyEvent 

ISpNotifySource::WaitForNotifyEveiit is a blocking call in response to a SAPI notification event. 
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A blocking call returns when a S API notification has fired, a timeout has passed or the initialized 
Win32 event object has signaled. This call is only valid after calling InitWin32Event. 

HRESULT WaitForNotifyEvent { 
DWORD dwMilliseconds 

); 

Parameters 

dwMilliseconds 

[in] Number of milliseconds for the timeout on a blocking call If set to INFINITE, there is no 
timeout. 

Return values 



Value 

S^OK 

SPERR_UNINITIALIZED 

E_FAIL 
FAILED (hr) 



Description 

Function completed successfully. 

InitWin32Event did not return successfully or has not been 
called. 

Interface not initialized. 
Appropriate error message. 

© 1995-2000 Microsoft Corporation, All rights reserved 



[This is preliminary documentation and subject to change,] 

ISpNotifySource::GetNotifyEventHandle 

ISpNotifySource::GetNofifyEventHandle retrieves the Win32 event object handle. 

HANDLE GetNotifyEventHandle ( void ) ; 
Parameters 

None 

Return values 



Value 

Win32 event object 

NULL 
FAILED (hr) 



Description 

Initialized by InitWin32Event on this ISpNotify Translator 
instance. 

Interface not initialized. 
Appropriate error message. 

© 1995_-2000_ Microsoft Corporation. All rights reserved 
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[This is preliminary documentation and subject to change.] 



ISpNotifySink 



In both speech synthesis and speech recognition, applications receive notifications when words have 
been spoken or when phrases have been recognized. SAPI components that generate notifications 
implement an ISpNotifySource. 

The ISpNotifySqurce and ISpNotifySink interfaces by themselves only provide a mechanism for a 
notification but no information on the events that caused the notification. With an ISpEventSource 
object, an application can retrieve information about the events that caused the notification. An 
ISpEventSource also provides the mechanism to filter and queue events. By default, an application 
(really an ISpNotifySink) receives no notifications fi"om ISpEventSource until Setlnterests has been 
called to specify on which events to notify or queue. 

When an application is notified of an event which is not queued, an application will take measures 
based on which event sink is receiving the notification. From context an application might know 
exactly what it needs to do, or it may need to interact with the components which sent the 
notifications. If an appHcation is notified of an event which is queued, then the appUcation will call 
ISpEventSource::GetEvents to retrieve the actual events that caused a notification. 

When to Implement 

Implement the ISpNotifySink interface when an ISpNotifySink object is to be notified. 
Methods in Vtable Order 

ISpNotifySink Methods Description 

Notify Notifies the ISpNotifySink object. 



ISpNotifySink: rNotify notifies an ISpNotifySink object when an event has occurred. 

If a message has not already been posted, this method either sets an event or posts a message to the 
private window. Often an application will call specific status functions based on the context of where 
a notification has come from. For instance, an application receiving a notification fi*om an ISpYpice 
instance can call I SpVoice:: Get Status to find out the most recent cause of a Notify call. 

HRESULT Notify ( void ) ; 
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Parameters 
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None 

Return values 

Value 

S_OK 

SPERR UNINITIALIZED 



Description 

Function completed successfully. 
Object has not been properly initialized. 



Microsoft Speech SDK 
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ISpNotifyTranslator 

ISpNotifyTranslator inherits from ISpNotifySink. 

The component CLSID_SpNotify, provides this interface for reuse by implementers of the 
ISpNotifySource interface. It provides a proxy object to other calls so that a developer does not need 
to re-address threading issues. Many, but not all, of these methods are identical to fliose in 
ISpNotifySource. 

When to Use 

ISpNotifyTranslator may be used in applications to pass in specific Win32 events. 
Methods in Vtable Order 



ISpNotifyTranslator Methods 
In itWindowMessage 

InitCallback 
InitSpNotifyCaliback 

ImtWin32Event 
W ait 

GetEventHandle 



Description 

Enables a window callback function to receive 
notifications as window messages. 

Enables a callback function to receive notifications. 

Enables an object derived from ISpTask to receive 
notifications. 

Sets up a Win32 event object to be used by this instance. 
A blocking call in response to a SAPI notification event. 
Retrieves notifications via Win32 events. 

© 1995-2000 Microsoft, Corporation All rights reserved. 
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file://C:\WIND0WS\TEMP\~hh2B 1 B.htm 



12/28/00 



Application-Level Interfaces 



Page 30 of 199 



ISpNotifyTranslator::InitWindowMessage sets up the instance to send window messages to a 
specified window. 

HRESULT InitWindowMessage( 
HWND hWnd, 
UINT Msg^ 
WPARAM wParam, 
LPARAM iParam 

); 

Parameters 

hWnd 

[in] Handle to the window whose message handler function will receive SAPI notifications. 

Msg 

[in] Message number which will be passed into the message handler function of the window 
hWnd, 
wParam 

[in] wParam that will be passed into the message handler function of the window hWnd, 
IParam 

[in] IParam that will be passed into the message handler function of the window hWnd 
Return values 

Value Description 

S OK Function completed successfully. 

SPERR_ALREADY JNITIALIZED Interface is already initialized. 
E_INV ALID ARG h Wnd is invalid or bad. 

FAILED(hr) Appropriate error message. 
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ISpNotifyTranslator : : InitCallback 

ISpNotifyTranslator::InitCallback sets up this instance to send notifications via a standard C-style 
callback function. 

HRESULT InitCallback ( 

SPNOTIFYCALLBACK *pfnCallhack, 
WPARAM wParam, 
LPARAM IParam 

); 

Parameters 

pfnCallback 

[in] The notification callback function to be used. 
wParam 

[in] Constant v^ord value that will be passed to the pfnCallback function when it is called. 
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IParam 

[in] Constant long value that will be passed to the pfhCallback function when it is called. 
Return values 



Value 

S_OK 

SPERR ALREADY INITIALIZED Interface is already initialized. 



Description 

Function completed successfully. 



E_INVALIDARG 
FAILED(hr) 



pfnCallback is invalid or bad. 
Appropriate error message. 
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ISpNotifyTranslator::InitSpNotifyCallback 

ISpNotifyTranslator::InitSpNotifyCallback sets up this instance to call the virtual method 
ISBNotifyCallback::N^^^ for notifications. 

HRESULT InitSpNotifyCallback( 

ISpNotifyCallback *pSpCallback, 
WPARAM wParam, 
LPARAM IParam 

) ; 

Parameters 



pSpCallback 

[in] A pointer to an application-defmed implementation of the ISpNotifyCallback interface. 
wParam 

[in] Constant word value that will be passed to the NotifyCallback method when it is called. 
IParam 

[in] Constant long value that will be passed to the NotifyCallback method when it is called. 
Return values 



Value 

S OK 



Description 

Fimction completed successfully. 



SPERR ALREADY_INITIALIZED Interface is already initialized. 



E_INVALIDARG 
FAILED(hr) 



pSpNotifyCallback is invalid or bad. 
Appropriate error message. 
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ISpNotifyTranslator::InitWin32Eveiit 

ISpNotifyTransIator::IiiitWin32Event sets up a Win32 event object to be used by this instance. 

This method is applicable only with objects using Win32 events. For an explanation of Win32 event 
objects see the Win32 Platform SDK documentation. 

Once an event object has been initialized for this instance, then use WaitForNotifyEvent and 
GetNotfyEventHandle methods. Win32 event objects and SAPI events are different. It is identical to 
ISpNoti:^Source::SetN except with two additional parameters. 

HRESULT InitWin32Event ( 
[in] HANDLE hEvent, 
[in] BOOL fCloseHandleOnRelease 

); 

Parameters 

hEvent 

Handle of an existing Win32 event object for the application to use with ISpNotifyTranslator. 
An ISpNotifyTranslator object will take care of all Win32 event object details. May be NULL, 
in which case an application may call ISpNotifyTranslator: : Wait to block a thread until a SAPI 
notification occurs. 
fCloseHandleOnRelease 

Specifies whether the hEvent handle should be closed when the object is released. If hEvent is 
NULL, then this ignore this parameter and always close the handle upon release of the object. 

Return values 

Value Description 

S OK Function completed successfully. 

SPERR_ALREADY_INITIALIZED Interface is already initialized. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corppratipn AUjightsxeserved 
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ISpNotifyTranslator: : Wait 

ISpNotifyTranslator: :Walt is a blocking call in response to a SAPI notification event. 

A blocking call returns when a SAPI notification has fired, a timeout has passed or the initialized 
WIN32 event object has signaled. This method is applicable only with objects using Win32 events. 

HRESULT Wait( 

DWORD dwMilliseconds 

) ; 
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Parameters 

dwMilliseconds 

[in] Number of milliseconds for the timeout on a blocking call. If set to INFINITE, there is no 
timeout. 

Return values 



Value 

S^OK 
S_FALSE 

SPERR UNINITIALIZED 



Description 

Function completed successfully. 

The event was not set and the call was timed out. 

InitWin32Event did not return successfully or has not been 

called. 
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ISpNotifyTranslator::GetEventHandle 

ISpNotifyTranslator::GetEventHandle returns the Win32 event object handle initialized by 
InitWin32Event on this ISpNotifyTranslator instance. This method is applicable only with objects 
using Win32 events. 

The handle is not a duplicated handle and should not be closed by the caller. 

HANDLE GetEventHandle ( void ) ; 

Parameters 

None 

Return values 



Value 

handle 

INVALID HANDLE VALUE 



Description 

The handle to the event 
Call failed. 
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ISpEventSink 
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This interface allows event sources to send events directly to an event sink through a free-threaded 
call. 

When to Implement 

This interface is never used by most applications. 
Methods in Vtable Order 

ISpEventSink Methods Description 

AddEvents Adds events directly to an event sink. 

GetEventlnterest Passes back the event interest for the voice. 



ISpEventSink:: AddEvents adds events directly to an event sink. 

HRESULT AddEvents ( 

const SPEVENT -^pEvent Array , 
ULONG ul Count 

); 

Parameters 

pEventArray 

Pointer to an array of SPEVENT event structures. 
ulCount 

Number of event structures being passed in. 
Return values 

Value Description 

S_OK Function completed successfully. 

E INVALIDARG pEventArray is bad or invalid 

FAILED(hr) Appropriate error message. 
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ISpEventSink: : AddEvents 
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ISpEventSink: : GetEventlnterest 
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ISpEventSink::GetEventInterest passes back the event interest for the voice. 

HRESULT GetEventlnterest { 

ULONGLONG *pull Event In teres t 

); 

Parameters 

pullE/VCfttlyitcTCs t 

[out] Set of flags of type SPEVENTENUM defining the event interest. 



Return values 

Value 

S_OK 

E_POINTER 
FAILED(hr) 



Description 

Function completed successfully. 
Pointer bad or invalid. 
Appropriate error message. 
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ISpEventSource 



This interface provides functionality for events which can be queued, filtered or can cause a 
notification to ISpNqti^Sink. 

The ISpEventSource inherits from the ISpNotifySource interface. 
Methods in Vtable Order 



ISpEventSource Methods 

S e t ln terest 

GetEvents 

Getlnfo 



Description 

Sets the types of events. 

Retrieves and removes the queued events. 

Retums queuing and interest information about the event. 

© 1995-2000 Microsoft Corporation All rights reserved 
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ISpEventSource: : Setlnterest 

ISpEventSource: :SetInterest sets the type of events which will invoke a notification and become 
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queued. 

If Setlnterest is never called, the speech recognition engine defaults to SPEI_RECOGNITION as the 
sole event interest. No events will be passed through if both parameters are set to zero. 



HRESULT Setlnterest ( 

ULONGLONG ull Even tint eras t , 
UIiONGLONG ullQueuedlnterest 

); 



Parameters 



uIlEventlnterest 

[in] Event ID flags indicating which events should invoke a notification to the event sink that 
this event source uses. 
ullQueuedlnterest 

[in] Event ID flags indicating which events should be queued prior to 
ISpEventSource:;GetEvents. The event flags set here must also be set in dwEventlnterest. 



Return values 



Value Description 

S_OK Function completed successfully. 

E_FAIL Interface not defined. 

FAILED(hr) Appropriate error message. 
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ISpEventSource: :GetEvents 

ISpEventSource::GetEvents retrieves and removes the events which have been queued. 



HRESULT GetEvents( 
ULONG ulConnt, 
SPEVENT *pEventArray , 
ULONG *puiFetched 



Parameters 



ulCount 

[in] Maximum number of events that SPEVENT structures can return. 
pEventArray 

[out] Pointer to array of SPEVENT structures. Each returned event is written to one of these 
SPEVENT structures, 
pulFetched 

[out] Pointer to the number of events returned. This number represents the earliest events to 
take place. These events are then removed from the queue. The events not returned are left for a 
future call to GetEvents. It is possible that by the time an application calls GetEvents, another 
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thread has processed the events and there are no events to be returned. This may be the result of 
subsequent Notify calls. 



Return values 

Value 

S_OK 

E_FAIL 

FAILED(hr) 



Description 

Function completed successfully. 
Interface not valid. 
Appropriate error message. 
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ISpEventSource: rGetlnfo 

ISpEventSouree::GetInfo passes back the information about the event. 

HRESULT GetInfo( 

SPEVENTSOURCEINFO *pInfo 

); 

Parameters 

pinfo 

[out] Pointer to a SPEVENTSOURCEINFO structure about the event. 
Return values 



Value 

S_OK 

E_FAIL 

FAILED(hr) 



Description 

Function completed successfully. 
Interface not valid. 
Appropriate error message. 
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ISpNotifyCallback 

Note: This is not a COM interface. 
Methods in Vtable Order 
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ISpNotifySource Methods 
No tilyC aUback 



Description 

Sets the notification mechanism for a particular instance. 
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ISpNotifyCallback::NotifyCallback 



ISpNotifyCallback::Notify Callback sets the notification mechanism for a particular instance. This 
method is not required to be defined and implementation is unique to the application. 



HRESULT NotifyCallback{ 
WPARAM wParam, 
LP ARAM 1 Par am 

); 

Parameters 

wParam 

[in] wParam that will be passed into the message handler function of the window hWnd. 
IParam 

[in] IParam that will be passed into the message handler function of the window hWnd. 
Return values 

Retum values are application dependent 
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Grammar Compiler Manager 



The following section covers: 



• Text grammar format 

• ISpGrammarBuilder 
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The context-free grammar (CFG) format in SAPI 5,0 defines the structure of grammars and grammar 
rules. Extensible Markup Language (XML) using the tagging language. The CFG compiler 
transforms the XML tags defining the grammar elements into a binary format used by speech 
engines. This compiling process can be performed either before or during application runtime. 
Speech recognition engines use CFGs to constrain the user*s words to words it will recognize. 



The following section covers: 



• Text grarmnar format overview 

• Syntax and tenm^^^^^^ 

• Grmmar rules 

• Designing granimar rules 

• Using grammar rules 

© 1 995-200_Q Microsoft Corporation, All rj^ts reserved 
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Text grammar format overview 

The Extensible Markup Language (XML) format inside a GRAMMAR XML element (block), is an 
"expert-only-readable" declaration of a grammar that a speech application uses to accomplish the 
following: 

• Improve recognition accuracy by restricting and indicatmg to an engine what words it should 
expect. 

• Improve translation of recognized speech into application actions. This is made easier by 
providing "semantic tags," 5)roperty name, and value associations) to words/phrases declared 
inside the grammar. 

A GRAMMAR XML element (block) appears in a XML source code file. The XML source is 
compiled into a binary grammar format and is the format used by SAPI during application runtime. 



The following section covers: 

• Extensible Markup Lan (XML) 

• Attributes 

• Contents 

• How SAPI utilizes XML information 

• Frequently used definitions 

• Non-empty concatenated recognition contents 

Extensible Markup Language 

The textual grammar format is an application of the XML. Every XML element consists of a start tag 
(<SOME_TAG>) and an end tag (</SOME_TAG>) with a case-sensitive tag name and contents 
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between these tags. The start tag and the end tag are the same if the element is empty. For example, 
the tag (<SOME_TAG/>). More information about XML and the XML specification is available 
at: http://www.w3.org/TR/REC-xml. 

Attributes 

Attributes of an XML element appear inside the start tag. Each attribute is in the form of a name 
followed by an equal sign followed by a string which must be surrounded by either single or double 
quotation marks. An attribute of a given name may only appear once in a start tag. 

In summary, the literal string cannot contain either < or if the string is surrounded by single 
quotation marks. It may not contain '\ if the string is surrounded by double quotation marks. 
Furthermore, use all ampersand (&) characters only in an entity reference such as & and >. 
When a literal string is parsed, the resulting replacement text will resolve all entity references such as 
> into its corresponding text, such as >. In this specification, only the resulting replacement text 
needs to be defined for attribute value strings. More information about XML and the XML 
specification is available at: http://www.w3.org/TR/REC-xml. 

Contents 

The contents of an element consists of text or subelements. Formal definitions of valid contents in 
this specification are provided as regular and "multi-set" expressions. The pseudo-element name 
"Text" indicates untagged text. With these definitions, the XML specification defines the exact file 
syntax details. 

:k Bac k to top 

How SAPI utilizes XML information 

SAPI uses XML content in the following two methods: 

1 . The SAPI context-fi-ee grammar compiler, compiles the XML grammar into a binary grammar 
format. The compiled binary grammar is loaded into the SAPI runtime environment fi^om a file, 
memory, or object (.DLL) resource. 

2. The speech recognition (SR) engine queries the runtime environment for available grammar 
information. 

a: Back to top 

Frequently used definitions 

Untagged text declaring a sequence of words that the recognition engine will recognize. Tentatively 
this text is only the not-necessarily-phonetic representation of words used for reading words v^hose 
pronunciation is unknown to the user (for example, for Japanese, kana, not kanji); this form will be 
called the spelling form. In further definitions in this section. Text will be referenced as though it 
were a pseudo-element. 

A Back to top 

Non-empty concatenated recognition contents 
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The contents of a number of XML elements in this specification such as, the P element, contain a 
sequence of grammar constructs which are concatenated together (one grammar construct after 
another). These grammar elements must be recognized in order for the contents defined to be 
recognized. 

The contents must be one of the following (and not both): 

Text and any number of L, P, O, or RULEREF elements in any order with at least one L, P, or 
RULEREF. 

For more information on the use of XML grammars, please see the Syntax and teminqlg section. 
X Back to top 
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Syntax and terminology 

The tags used for in the Speech Text Grammar Format (STGF) are defined using the following XML 
syntax: 



Element 


Attributes 


Description 


GRAMMAR 


LANGID, 


Grammar definition 




WORDTYPE, 
LEXDELIMITER 




DEFINE 


None 


Defines grammar constants. 


ID 


NAME,VAL, 


Defines property name id. (10 bit) 




VALSTR 




RULE 


NAME, ID, 

TOPLEVEL, 

EXPORT, 

INTERPRETER, 

DYNAMIC, 

TEMPLATE 


Rule definition (non-terminal) 


RULEREF 


NAME, REFID, 


Rule reference (non-terminal) 




OBJECT, URL, 
PROPNAME, 
PROPID, VAL, 
VALSTR, 
WEIGHT 




PHRASE or P 


PROPNAME, 
PROPID, VAL, 
VALSTR, PRON, 
DISP, MIN, MAX, 
WEIGHT 


Phrase 
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OPT or O 



LIST or L 



DICTATION 
RESOURCE 



TEXTBUFFER 



WILDCARD 



PROPNAME, Optional phrase 
PROPID, VAL, 
VALNUM, MAX, 
MIN 



PROPNAME, 
PROPID, VAL, 
VALSTR 

MIN, MAX, 
PROPID 

NAME 

PROPNAME, 

PROPID, 

WEIGHT 

None 



List of alternate phrase elements. 
Transition to a dictation grammar. 

Transition to a textbuffer grammar. 

Garbage identifier for one or more non-silence soimds. 



X Back to top 

GRAMMAR 

Grammar definition 

The top-level XML element containing all other XML elements needed to declare one grammar. 



GRAMMAR 

One or more RULE elements. 

<RULE>+, <DEFINE>? 



Tag name: 

Contents: 

Contents 
(formally): 

Attributes: 

LANGID ^ , 

String specifying the language identifier associated with the grammar. The language identifier 
is specified as a hexadecimal value. For example, the LANGID for English (US) expressed in 
the hexadecimal form is 0x0409. 

WORDTYPE _ ^ A- 

String specifying the grammar word type. One of the grammar word types specitied in the 
SPGRAMMARWORDTYPE enumeration sequence. Note: Only SPWT LEXICAL is 
supported in this release of SAPI. 

LEXDELIMITER 

Back to top 

DEFINE 

The DEFINE tag specifies a group of ID tags. 

Attributes: 

None. 



Back to top 
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ID 

The ID tag defines named constants for RULE, PROPNAME elements. 
Attributes: 

NAME . , . 

The name of the property id to be defined. Single or double quotation marks surround valid 

entries. 

VAL 

Integer value associated with NAME in the range of 0 to 1023. 
A B a ck to top 

RULE 

Rule definition (non-terminal) 

Defines a grammar rule, (non-terminal in CFG terminology) only for use internally within a 
grammar. A rule defined in a RULE element cannot be referenced by another grammar and cannot be 
activated or deactivated at runtime. For more information on grammar types, see 
SPCFGRULEATTRIBUTES . The tag name is RULE, the contents must be non-empty concatenated 
recognition contents and the attributes are as follows: 

Attributes: 

NAME . ^ ^. 1. J . 1, . 

(Required) Textual case-sensitive name of rule to be referenced internally and externally to 
this grammar. These rules may be activated and deactivated at runtime. Other grammars 
reference these rules. The replacement text string resulting firom this attribute value must 
satisfy the requirements for a rule name in the binary grammar format. The name must be 
vmique within a grammar. 

^ Specifies the constant value or VARIANT type (VT_UI4) identifying the RULE. 

TOPLEVEL . ^ ^ . . 1 1 , 

Attribute that indicates that this is a top-level rule. Activate and deactivate top-level rules 
individually by the application. The value of this attribute, either "ACTIVE" or 
"INACTIVE" (default) indicates whether or not the rule should be active after loadmg. 

Note: When a grammar rule is imported by another grammar rule, the "INACTIVE" state of a 
rule is assumed. 

EXPORT 

Specifies if the rule can be imported by another grammar rule. Set the attribute value to either 0 
or 1 to control the state of this rule. For example, set the attribute to EXP0RT="1" to enable 
other grammar rules to import the rule; set the attribute to EXPORT="0" when the rule is not 
intended to be imported by another rule. 

INTERPRETER , ^ , , . n 

Value indicating whether this is an interpreted grammar rule. Set the attnbute value to either u 
or 1 to control the state of this rule. For example, set the attribute to INTERPRETER="1", to 
indicate this is an interpreted rule; set the attribute to INTERPRETER="0" when the grammar 
rule is not intended as an interpreted rule. 

DYNAMIC 
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Value indicating whether this is a dynamic rule. Set the attribute value to either 0 or 1 to 
control the state of this rule. For example, set the attribute to DYNAMIC="1", to use the rule 
dynamically; set the attribute to DYNAMIC="0" when the rule is not intended for dynamic 
use. 

Note: When specifying that a grammar RULE be used dynamically, its contents must be 
empty. When a grammar RULE is dynamic its contents are modifiable. 



TEMPLATE 

Specifies the contents of the RULE attribute are replaced by the stnng value of the 
PROPNAME. For example, TEMPLATE="$PROPNAME$" is replaced by the contents of 
PROPNAME. 



X Back to top 



RULEREF 



Rule reference (non-terminal) 

Use this element inside the contents of a rule definition (RULE) to reference another defined rule. 



Tag name: RULEREF 

Contents: Empty (no contents) 



Attributes: 

NAME ^ , ^1 

Specifies the name of the referenced rule. A rule that has not yet been declared in the tile may 

be referenced. 
REFID 

Constant value or VARIANT type (VT_UI4) identifying the RULEREF. 
OBJECT , . . 

Specifies the class identifier (CLSID) or programmatic identifier (ProgID) that is associated 
with the RULEREF. 

URL 

Specifies that the referenced rule should be loaded from a stored file, resource, or Internet 
location. 

file://directory_name/some_file_name.xml 

res://directory_name/some_resource.dll 

http://www.microsoft.com/some_resource.dll 

PROPNAME 

(Optional) except if a VAL attribute is present. 

The case-sensitive and possibly non-unique name of zero length whose XML replacement text 
(see XML attribute syntax above) is the semantic property name to be associated with 
recognition of this rule in the context of wherever this tag reference is present. Wherever this 
rule reference element is present, all property name/value pairs recognized by this rule will add 
PROPNAME to the front of the property name followed by a period. 
PROPID 

(Optional) The identifier of the PROPNAME element. 

VAL 

(Optional) Semantic value for property specified by attribute PROPNAME. 
The recognized text of this rule reference will be used as the property value if this attribute is 
omitted when a PROPNAME is present. 
VALSTR 
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(Optional) String containing the identifier of the VAL element. 
WEIGHT 

Specifies the relative list position of the RULEREF and is expressed as a float value. 
-x. Back to top 

PHRASE or P 

Phrase 

The tag name is P, the contents mtist be non-empty, concatenated, recognition contents (as defined 
above). These attributes are: 

Attributes: 

PROPNAME , . f 

The replacement text (see XML attiibute syntax above) of this attribute value is the name ot 
the semantic property to be associated with the recognition of this expression. 
PROPID 

(Optional) The identifier of the PROPNAME element. 

VAL 

(Optional) Semantic value for property specified by attribute PROPNAME. 
VALSTR 

(Optional) String containing the value identifier of the property. 
PRON 

Specifies a pronunciation for a single text word in the SAPI phoneme set. 

For more phoneme related information, please see the American En glish phoneme 

representation section. 

DISP , ^, . , . . 

Specifies the string contents of the display form of a text phrase element. The sXnng contaimng 
the display form can be from zero to 255 characters in length. 

MIN 

(Optional) The default value for this is 1. The valid range of values for this is 0 to 255 and 
must be less than the value specified in MAX. Note: The value specified by MAX will be used 
when the specified MIN value is greater than the MAX value. 

(Optional) The default value for this is 1 . The valid range of values for this is 1 to 255, or 
indicated by "INF" in text. , 
This value indicates the maximum number of times valid recognitions ol this element s 
contents may be recognized repeatedly. A value "INF" indicates that any number of 
recognitions may occur. 
WEIGHT ^ , , 

Specifies the relative list position of the PHRASE and is expressed as a float value. 



X Back to top 

OPT or O 



Optional phrase 

This element is similar to the P element. The exception being that the O element is optional. An 
associated property name and value pair will be generated only if tiie contents of this element are 
recognized. 
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Contents: Text or any number of L, P, O, or RULEREF elements in any order. 

Contents Text | ( L | P | O | RULEREF )+ 
(formally): 

Attributes: 

PROPNAME , f 

The replacement text (see XML attribute syntax above) of this attnbute value is the name ot 
the semantic property to be associated with the recognition of this expression. 
PROPID 

(Optional) The identifier of the PROPNAME element. 

VAL 

(Optional) Semantic value for the property specified by attribute PROPNAME. 
VAXjSTR 

(Optional) String containing the value identifier of the PROPNAME element. 

(Optional) The default value for this is 1. The valid range of values for this is 1 to 255, or 
indicated by "INF" in text. 

This value indicates the maximum number of times valid recognitions of this element's 
contents may be recognized repeatedly. A value "INF" indicates any number of recognitions 
may occur. 

MIN 

(Optional) The default value for this is 1 . The valid range of values for this is 0 to 255 and 
must be less than the value specified in MAX. Note: The value specified by MAX will be used 
when the specified ME^ value is greater than the MAX value. 

This value indicates the minimum number of times valid recognitions of this element's contents 
may be recognized repeatedly. 

■X. Back to top 

LIST or L 

List of alternate phrase elements 

Defines an expression of alternate phrase recognitions. Each subelement represents a possible 
separate recognition in place of this element. 

Tag name: L 

Contents P+,L, RULEREF 
(formally): 

Attributes: 

PROPNAME , . 

The replacement text (see XML attribute syntax above) of this attribute vdue is the name ot 
the semantic property to be associated with the recognition of this expression. 
PROPID 

(Optional) The identifier of the PROPNAME element. 

VAL 

(Optional) Semantic value for the property specified by attribute PROPNAME. 
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(Optional) String containing the value identifier of the PROPNAME element. 
A Back to top 

DICTATION 

Specifies the grammar node is a dictation grammar. 

Attributes: 

PROPNAME 

(Optional) except if a VAL attribute is present. 

The case-sensitive and possibly non-unique name of zero length whose XML replacement text 
(see XML attribute syntax above) is the semantic property name to be associated with 
recognition of this rule in the context of wherever this tag reference is present. Wherever this 
rule reference element is present, all property name/value pairs recognized by this rule will add 
PROPNAME to the fi-ont of the property name followed by a period. 

VAL 

Specifies the dictated text. 
PROPID 

(Optional) The identifier of the PROPNAME element. 

MIN 

(Optional) The default value for this is 1. The valid range ofvalues for this is 0 to 255 and 
must be less than the value specified in MAX. Note: The value specified by MAX will be used 
when the specified MIN value is greater than the MAX value. 

^^^^ (Optional) The default value for this is 1 . The valid range ofvalues for this is 1 to 255, or 
indicated by "INF" in text. ^. ^ .. , 

This value indicates the maximum number of times valid recognitions ot this element s 
contents may be recognized repeatedly. A value "INF" indicates that any number of 
recognitions may occur. 

x Back to top 

RESOURCE 

Specifies the grammar node is a resource grammar. 
Attributes: 

^^^The text string containing the NAME and VALUE information associated with this resource. 
A Back to top 

TEXTBUFFER 

Specifies the grammar is from a null-terminated string. 

Attributes: 

PROPNAME 

(Optional) except if a VAL attribute is present. 
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The case-sensitive and possibly non-unique name of zero length verbose XML replacement text 
(see XML attribute syntax above) is the semantic property name to be associated with 
recognition of this rule in the context of wherever this tag reference is present. Wherever this 
rule reference element is present, all property name/value pairs recognized by this rule will add 
PROPNAME to the front of the property name followed by a period. 

VAL 

(Optional) Semantic value for the property specified by attribute PROPNAME. 
PROPID 

(Optional) The identifier of the TEXTBUFFER grammar element. 

WEIGHT ^. J ri . 

Specifies the relative list position of the TEXTBUFFER grammar and is expressed as a float 

value. 
:s Back to top 

WILDCARD 

Specifies a garbage word identifier for one or more non-silence sounds. 

Attributes: 
None 

A Back to top 

e> 1 995-2000 Microsoft Corporation. All rights reserved 



[This is preliminaiy documentation and subject to change.] 

Grammar rules 

Grammar rules are elements that SAPI 5.0 compliant recognition engmes use to restrict the possible 
word or sentence choices during the speech recognition process. Recogmtion engines use grammar 
rules to control the elements of sentence construction by utilizing the predetenriined list of 
recognized word or phrase choices. This list of recognized words or phrase choices contained in ttie 
grammar rules forms the basis of the recognition engine vocabulary. 

The phrase or sentence uses each grammar rule element to determine the recognition path. 

For example, examine the phrase describing travel plans, "I would like to travel fi-om Seattle to New 
York " and note that there are elements that determine the resulting information. In this example, a 
person is planning to fly to New York from Seattle . This is a very simple illustration of what could be 
a very complex problem. Determining the same travel plans without limitmg the method, direction, 
and travel destination would result in an infinite number of travel options. 

The resulting information can be determined by restricting the available choices for a given 
sentence. Through this method, the resulting information can be composed only from certain 
available choices, thus eliminating the possibility of an infinite number of travel plan 
combinations. 
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I would like to travel from Seattle to New York. 

I 

[Method] 

/ \ 
Fly Drive 

[Direction] 

/ \ 

From To 

[City] 

Seattle 
New York 
Los Angeles 
Albuquerque 

[Direction] 

/ \ 
To From 

[City] 

Seattle 
New York 
Los Angeles 
Albuquerque 



The elements of interest in the example phrase are as follows: 

• Method of travel (fly or drive) 

• Travel direction (from or to) 

• The city of origin for the travel plan (from) 

• The city of destination for the travel plan (to) 

I would like to travel from Seattle to New York. 

Grammar rules become concatenated phrase elements. These phrase elements are lirnited to the 
defined set of grammars. Control can be significantly improved over the resultmg mformation by 
restricting the input choice to a limited set of possibilities. Otherwise, obtammg the travel plan 
information from the same sample phrase, "I would like to travel from Seattle to New York, would 
be considerably more ambiguous. 

The complexity of parsing the same sentence increases exponentially without using a defined set of 
choices Imagine the possible number of combination in a sentence that is not restncted to a tmite hst 
of combinations. For example, examine the possible choice combinations by movmg the mouse over 
the following sentence. 

To display the available choice selections in the example phrase, move the mouse over the underlined 
text below: 
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"I want to — (unknown travel method) — (unknown travel direction) — (unknown city) — 
(unknown travel direction) (unknown city) /' The amount of predictable information is significantly 
reduced without the ability to constrain the available choices within a sentence. 

Grammar rules apply to the following: 

TOPLEVEL 

A grammar tagged as TOPLEVEL can be in an active or inactive state. The rules that import a 
grammar can override the activation state of a rule. This conditional state can be configured 
dynamically at runtime. If an inactive grammar is included in another grammar or grammar 
rule, ignore the inactive state. When a rule is activated, a speech recognition engine will accept 
only speech satisfying at least one of the active rules contained in the loaded grammar. 
Non-terminal 

A grammar node is considered to be non-terminal if it is the beginning of a choice selection or 
a group of choice selections. For example, the grammar node Dog is non-terminal when the 
subsequent choice selections are types of dogs. This type of grammar is defined as non- 
terminal because of its choice selections. 
Terminal 

A grammar node is considered to be terminal if it's the only word in the recognized vocabulary 
which can be spoken. Using the Dog example above, terminal grammar nodes are the type of 
dogs. 



Cat- 



Animal 



/--+--\ 
■/ \- 



Burmese 
-f--- Himalayan 
Persian 
Siamese 



-Dog 



+ ■ 
■ + 



-- Non- terminal 



■ + 

+ Non-terminal 



Airedale 
Poodle 
Schnauzer 
Whippet 



+ Terminal nod 



The text format grammar XML tags follow block scope methods that are similar to HTML tags. That 
is, each tag has an opening tag and a corresponding closing tag. There is more information about 
XML syntax in the Syntax and terminology section. 

XML tag syntax Contents 

<sometag NAME="some_name" Start of "sometag" tag scope which includes 

VAL="some value"> the name and value information, 

</sometag> End of the "sometag" scope. 

Back to top 
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[This is preliminaiy documentation and subject to change.] ^ 

Designing grammar rules 

Speech applications often use context-free grammars (CFG) to parse the recognizer output and in 
some instances, to act as the recognizer's language model. A speech recogmtion engme uses the Ltij 
to constrain the words it will recognize that are contained in the user's utterance. It the Ct O is 
augmented with semantic information (property names and property values as explamed below), then 
a SAPI component converts the recognized word string into a name/value-meanmg representation. 
The application then uses the meaning representation to control its part of the conversation with the 



user. 



For example, the phrase "Please schedule a meeting with Amy Anderson" could be annotated as 
follows: 



Phrase element 



Grammar element 



Conte 



"schedule a meeting" 
"with" 

"Amy Anderson" 



"request: meeting" 
"participants : " 
"<email alias>" 



// attri 
// only 
/ / value 



Defining the different grammar element components could result in the following: 
Please schedule a meeting with Amy Anderson . 



request: meeting 

participants 



AmyAnd 



The example sentence "Please schedule a meeting with Amy Anderson" generates the following 
SAPI 5.0 grammar: 



<RULE TOPLEVEL= ACTIVE > 

<P PROPNAME=" request" VAL= "meeting" >schedule a meet 
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<P>with</P> 

<LN PROPNAME= "participants "> 

<PN VAL="AmyAnd">Amy Anderson</PN> 

<PN VAL="tbremer">Ted Bremer</PN> 

<PN VAL="fralee">Frank Lee</PN> 

<PN VAL="crandall">Cynthia Randall</PN> 

<PN VAL="swhite">Suki White</PN> 

<PN VAL="kyoshida">Kim Yoshida</PN> 

</LN> 
</RULE> 



The result of saying the example sentence "Please schedule a meeting with Amy Anderson" would be 
as follows: 

requestrmeeting 

participaiits:AmyAnd 



© 1995-2000 Microsoft Corporation All rights reserved 



[This is preliminaty documentation and subject to change,] 1^ 

Using grammar rules 

Grammar rules define sentence contents and phrase elements. Each grammar and grammar element 
determines the recognition engine's ability to effectively construct phrase elements. Phrases and sub- 
expressions are commonly represented by a separate rule and combined into larger phrases and 
sentences with higher level rules. For more information, see the Ckammar rules section. 

The following example illustrates how to implement a grammar for a game of solitaire. 

<GRAMMAR LANGID="1033"> 
<DEFINE> 

<ID NAME="FROM" VAL="l"/> 

<ID NAME="TO" VAL="2"/> 

<ID NAME="SUIT" VAL="3"/> 

<ID NAME=" COLOR" VAL="4"/> 

<ID NAME="RANK" VAL="5"/> 

<ID NAME="ColorRed" VAL=" 11101 "/> 

<ID MAME="ColorBlack" VAL= " 10011 " /> 
< /DEFINE > 

<RULE NAME="newgame" TOPLEVEL="ACTIVE" > 

<P>new +game</P><0>-please</0> 
</RULE> 

<RULE NAME="playcard" T0PLEVEL= "ACTIVE" EXP0RT="1"> 
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<RULE NAME="playcard" TOPLEVEL= "ACTIVE " EXP0RT="1"> 
<0>please</0> 
<P>play the</P> 
<0> . . . </0> 

<RULEREF REF="card"/> 
<0>please</0> 
</RULE> 

<RULE NAME="movecard" TOPLEVEL= "ACTIVE " > 
<0>please</0> 
<P> 

<L> 

<P>move</P> 
<P>put</P> 
</L> 

<P>the</P> 
</P> 

<RULEREF PROPNAME="from" PROPID="FROM" NAME="card"/> 
<0> 

<L> 

<P>on</P> 
<P>to</P> 
</L> 

<P>the</P> 

<RULEREF PROPNA]y[E="to" PROPID="TO" NAME= " card" /> 
</0> 

<0>please</0> 
</RULE> 

<RULE NAME="card"> 
<L> 

<P> 

<LN PROPNAME=" color" PROPID=" COLOR" > 
<PN VAL="ColorRed">red</PN> 
<PN VAL="ColorBlack">black</PN> 

</LN> 

<RULEREF NAME= " rank " / > 
</P> 
<P> 

<RULEREF NAME="rank"/> 
<0> 

<P>of </P> 

<LN PROPNAME="SUit" PROP ID= "SUIT" > 
<PN VAL="0">clubs</PN> 
<PN VAL="l">hearts</PN> 
<PN VAL="2">diamonds</PN> 
<PN VAL="3">spades</PN> 
</LN> 
</0> 
</P> 

<LN PROPNAME="suit" PROPID="SUIT" > 
<PN VAL="0">club</PN> 
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<PN VAL="l">heart</PN> 
<PN VAL="2">diamond</PN> 
<PN VAL="3">spade</PN> 



</LN> 
</L> 
</RULE> 

<RULE NAME="rank"> 

<LN PROPNAME="rank" PROPID="RANK" > 
<PN VAL="l">ace</PN> 
<PN VAL="2">two</PN> 
<PN VAL="3">three</PN> 
<PN VAL="4">four</PN> 
<PN VAL="5">f ive</PN> 
<PN VAL="6">six</PN> 
<PN VAL="7">seven</PN> 
<PN VAL="8">eight</PN> 
<PN VAL="9">nine</PN> 
<PN VAL="10">ten</PN> 
<PN VAL="ll">jack</PN> 
<PN VAL="12">queen</PN> 
<PN VAL="13">king</PN> 
<PN VAL="12">lady</PN> 
<PN VAL="13">emperor</PN> 
</LN> 
</RULE> 
</GRAMMAR> 



A Back to top 



Microsoft Speech SDK 
with SAP! 5.0 



[This is preliminaiy documentation and subject to change.] 
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ISpGrammarBuilder 



Methods in Vtable Order 



ISpGrammarBuilder Methods 
ResetGrammar 



GetRule 
ClearRule 



CreateNewState 



Description 

Resets all grammar rules and specifies an optional 
grammar. 

Retrieves grammar rule information. 

Removes the state information associated with a grammar 
rule. 

Creates a new state in the same grammar rule. 
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AddWordTransitiqn Changes a phrase from the display form and adds each 

word individually to the granmiar. 

AddRuleTransition 

AddResource 

Com mit 

© 1995^2000 MicxqsoftCprporati^^^^^^ Ail rights„reseryed 



[This is preliminary documcBtation and subject to change. ] ^pi 

Example application of ISpGrammarBuilder 

The code example below illustrates an implementation of the ISpGrarmaarBuilder interface. 

TPR t_ISpGrammarBuilder_ThankYouExample {ISpGrammarBuilder* pGrammarBuilder , LPCSTR 

// This test implement a small but compete example application using 

/ / I SpGrammar Bu i 1 de r 

// THANKYOU ::= THANK (YOU)? 

// THANK : := Thanks 

// THANK ::= Thank you (very much)? 
// YOU Mary | Mike | Sam 

HRESULT hr = S_OK; 
int tpr = TPR__PASS; 

SPSTATEHANDLE hStateTHANK; // the starting node of rule THANK 

SPSTATEHANDLE hStateThankl , 
SPSTATEHANDLE hStateThank2 . 
SPSTATEHANDLE hStateThank3 , 

SPSTATEHANDLE hStateYOU; // the starting node of rule YOU 

SPSTATEHANDLE hStateTHANKYOU; // the starting node of rule THANKYOU 

SPSTATEHANDLE hStateThankYoul ; 

CSpCoTaskMemPtr<SPBINARYGRAMMAR> cpBinaryGrammar ; 
// define rule THANK 

DOCHECKHREX{hr = pGrammarBuilder->GetRule (L" THANK", 1, 0, TRUE, &hStateTHANK) ; 
DOCHECKHREX (hr - pGrammarBuilder- >Cr eat eNewS tat e (hStateTHANK, SchStateThankl) ; ) 
DOCHECKHREX (hr = pGrammarBuilder- >CreateNewS tat e (hStateTHANK, S:hStateThank2) ; ) 
DOCHECKHREX (hr = pGrammarBui lder->CreateNewS tat e (hStateTHANK, &hStateThank3 ) ; ) 
// THANK : := Thanks 

DOCHECKHREX (hr = pGrammarBuilder->AddWordTrans it ion (hStateTHANK, NULL, L"Thank 
// THANK ::= Thank you (very much)? 

DOCHECKHREX (hr = pGrammarBuilder- >AddWordTrans it ion (hStateTHANK, hStateThankl, 
DOCHECKHREX (hr = pGrammarBuilder- >AddWordTrans it ion (hStateThankl , hStateThank2 
DOCHECKHREX (hr = pGrammarBuilder- >AddWordTransition (hStateThank2 , hStateThankS 
DOCHECKHREX (hr = pGrammarBuilder- >AddWordTrans it ion (hS tat eThank 3 , NULL, L"much 
DOCHECKHREX (hr = pGrammarBuilder- >AddWordTrans it ion (hStateThank2 , NULL, NULL, 

// define rule YOU 

DOCHECKHREX (hr = pGrammarBuilder- >GetRule(L" YOU", 2, 0, TRUE, &hStateY0U) ; ) ; 
// YOU ::= Mary | Mike | Sam 
// TODO: property? 

DOCHECKHREX (hr = pGrammarBui lder->AddWordTrans it ion (hS tat eYOU, NULL, L"Mary", 

DOCHECKHREX (hr = pGrammarBuilder- >AddWordTrans it ion (hS tat eYOU, NULL, L"Mike", 

DOCHECKHREX (hr = pGrammarBuilder- >AddWordTrans it ion (hStateYOU, NULL, L"Sam", L 

// define rule THANKYOU 

DOCHECKHREX (hr = pGrammarBuilder- >Get Rule (L" THANKYOU" , 3, SPRAF__TopLevel , TRUE 
DOCHECKHREX (hr = pGrammarBuilder- >Cr eat eNewState (hStateTHANKYOU, &hStateThankY 
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// THANKYOU THANK (YOU)? 

DOCHECKHREX{hr = pGrammarBuilder- >AddRuleTransition (hStateTHANKYOU, hStateThan 
DOCHECKHREX(hr = pGrammarBuilder->AddRuleTransition (hStateThankYoul, NULL, hSt 
DOCHECKHREX (hr = pGrammarBuilder- >AddWordTrans it ion (hS tat eThankYoul , NULL, NUL 

// TODO: loop? 

hr = pGrammarBuilder->Commit (0) ; 

CheckHr(hr, tpr, "Example failed when Commit (0) .") ; 
return tpr; 

} 

© 1995-2000 Microsoft Corporation. AU ri^hts^re^ 



[This is preliminary documentation and subject to change,] IgJ 

ISpGrammarBuilder : :ResetGrammar 

ISpGrammarBuilder::ResetGrammar resets all grammar rules and specifies an optional grammar. 

HRESULT ResetGraznmar ( 
LANGID NewLanguage 

); 

Parameters 

NewLanguage 

[in] Language identifier associated with the grammar rule. 

Return values 

Value Description 

S_OK Function completed successfully. 

FAILED(hr) Appropriate error message. 



Example 



The following code snippet illustrates the use of ResetGrammar. 
{ 

HRESULT hr = S_OK; 
int tpr = TPR_PASS; 

//============================ ===™ ==================..=™.^.=..=™==== = 

TEST TOPIC - "ResetGrammar when no rules"; 

//====================== — ======= — == — ========= — ====== — ====== 

hr = pGrammarBuilder- >ResetGrammar (1033) ; 
CheckHr{hr, tpr, TEST_TOPIC) ; 

TEST TOPIC = "Set language to default user language"; 

hr = pGrammarBuilder->ResetGraramar (SpGetUserDefaultUILanguage () ) ; 
CheckHr(hr, tpr, TEST_TOPIC) ; 
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TEST_TOPIC = "Set language to non-english" ; 

hr = pGrammarBuilder->ResetGrammar (MAKELANGID(LANG_CHINESE, SUBriANG_CHIIsrESE_SI 
CheckHr(hr, tpr, TEST_TOPIC) ; 

hr = pGrammarBuilder->ResetGrammar(iy[AKEIiANGID(LANG_ JAPANESE, SUBLANG__DEFAULT) ) 
CheckHr(hr, tpr, TEST_TOPIC) ; 



return tpr; 

} 



© 1995-2000 Microsoft Coiporation. Al] rights reserved 



[This is preiiminarv^ documentation and subject to change.] ^ 

ISpGrammarBuilder: :GetRule 

ISpGrammarBuilder::GetRule retrieves grammar rule information. 



HRKSULT GetRule( 

const WCHAR '^pszRuleName, 

DWORD dwRuleld, 

DWORD dwAttrihutes , 

BOOL fCrea telfNotExist, 

SPSTATEHAISIDLE *phInitialState 

); 



Parameters 

pszRuleName 

[in] Address of the null-terminated string containing the grammar rule name. If NULL, no 
search is made for the name. 
dwRuleld 

[in] Grammar rule identifier. If zero, no search is made for the rule ID. 
dwAttributes 

[in] Grammar rule attributes. 
fCreatelfNotExist 

[in] Boolean indicating that the grammar rule is to be created if one does not currently exist. 
TRUE allows the creation; FALSE does not. 
phlnitialState 

[out] The initial state of the rule. May be NULL. 

Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG At least pszRuleName phlnitialState is invalid or bad. 

AlXtrndiitly, pszRuleName is NULL or dwRuleld is zero. 

E_OUTOFMEMORY Not enough memory to complete operation. 

SPERR_RULEJSfOT_FOUND No rule matching the specified criteria can be found. 

SPERR_RULE_NAME_ID_CONFLICT More than one rule with the same name and ID was 

found. 

FAILED(hr) Appropriate error message. 
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m 



Example 

The following code snippet illustrates the use of GetRule. 



HRESULT hr = S_OK; 
SPSTATEHANDLE hState; 



// 
// 

// 
// 

// 



// 



TEST_TOPIC = "Create 


a rule with id" ; 








hr = pGr ammar Builder - 
//Check return value 


- >GetRule (L " rulel " , 1 , 


SPRAF Dynamic, 


TRUE, 


S:hState) ; 


TEST__TOPIC = "Create 


a rule without id" ; 








hr = pGrammarBuiider- 
//Check return value 


- >GetRule {L"rule2 " , 0 , 


S PRAF_Dynami c , 


TRUE, 


SihState) ; 


TEST_TOPIC = "Get an 


existing rule by id" ; 








hr = pGrammarBuilder- 
//Check return value 


->GetRule(L"rulel", 1, 


SPRAF_Dynamic , 


TRUE, 


&hState) ; 


TEST TOPIC = "Get an 


existing rule by name 









©_1 995-2000 Microsoft CoiT^oratjon^ AJLri^hts_reseryed. 



II- 

hr = pGrammarBuilder->GetRule{L"rulel", 0, SPRAF_Dynamic, TRUE, &hState) ; 
fg //Check return value 

w 

01 



fIJ [This is preiiminaiT docimientation and subject to change.] 

m 

ISpGrammarBuilder : :ClearRule 

B 

ISpGrammarBuilder: rClearRule removes the state information associated with a grammar rule. 

HRESULT ClearRule{ 

SPSTATEHANDLE hState 

); 

Parameters 

hState 

Return values 

Value Description 

S_OK Function completed successfully. 

FAILED(hr) Appropriate error message. 
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Example 

The following code snippet illustrates the use of ClearRule. 
{ 

HRESXJLT hr = S_OK; 
int tpr = TPR_PASS; 

SPSTATEHANDLE hinit; 
SPSTATEHANDLE hState; 

DOCHECKHREX(hr = pGramTnarBuilder->GetRule(L"rulel", 1, 0, TRUE, &hlnit);); 

// = = = = == = ™. = = = = = = :..= = = = = = = = = .= . = = ™ = = = = = = = = ^^^^^ = = = = = = = = = = = = = ™ = = 

TEST_TOPIC = "ClearRule using hInitState" ; 



DOCHECKHREX (hr = pGrammarBuilder- >CreateNewState (hInit , &hState) ; ) ; 
DOCHECKHREX (hr = pGrammarBuilder- >AddWordTransition (hlnit , hState, L"word", NU 
hr = pGrammarBuilder- >ClearRule (hlnit) ; 
CheckHr(hr, tpr, TEST_TOPIC) ; 

hr = pGrammarBuilder- >AddWordTransition (hlnit, hState, L"word", NULL, SPWT_LEX 
CompareHr (hr, E_INVALIDARG, tpr, CatMsg (TEST_TOPIC, ": not really cleared. ")) ; 



TEST TOPIC = "ClearRule using hState 1- hlnit"; 



DOCHECKHREX (hr = pGrammarBuilder- >CreateNewState (hlnit , SJiState) ; ) ; 
DOCHECKHREX (hr = pGrammarBuilder- >AddWordTrans it ion (hlnit , hState, L"word", NU 
hr - pGrammarBuilder- >ClearRule (hState) ; 
CheckHr(hr, tpr, TEST_TOPIC) ; 

hr = pGrammarBuilder- >AddWordTransit ion (hlnit, hState, L"word" , NULL, SPWT_LEX 
CompareHr (hr, E_INVALIDARG, tpr, CatMsg (TEST_T0PIC, ": not really cleared. ")) ; 

return tpr; 

} 

© 1995^000 MicxQSoftCo^^ reserved. 



[This is preiiminar>'' documentation and subject to change.] ^SS 

ISpGrammarBuilder::CreateNewState 

ISpGrammarBuilder::CreateNewState creates a new state in the same grammar rule. 

HRESULT CreateNewState ( 

SPSTATEHAlilDLE JiState, 
S P STATEHANDIiE *phState 

); 



Parameters 



hState 

Handle to the grammar rule information. 
phState 

Address of the handle containing the grammar rule state information. 
Return values 



Value Description 
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S_OK Function completed successfully. 

E_INVALIDARG One or more arguments are invalid. 

FAILED(hr) Appropriate error message. 

Example 

The following code snippet illustrates the use of CreateNewState. 
{ 

HRESULT hr = S_OK; 
int tpr = TPR_PASS; 

SPSTATEHANDLE hinit; 

DOCHECKHREX(hr = pGrammarBuilder->GetRule(L"rulel", 1, 0, TRUE, Srhlnit);); 

TEST_TOPIC = "CreateNewState using the hInitState"; 
SPSTATEHANDLE hState; 

hr = pGrammarBuilder->CreateNewState (hInit, &hState) ; 
CheckHr{hr, tpr, TEST_TOPIC) ; 

//^_^___^__=_.___.__===_=__=============.=========™= 

TEST_TOPIC = "CreateNewState using hState 1= hInit"; 
//==.===.============™========================================™=== 

SPSTATEHANDLE hState2 ; 

hr = pGrammarBuilder->CreateNewState (hState, 5chState2) ; 
CheckHr(hr, tpr, TEST_TOPIC) ; 

return tpr; 

} 

© 1995-2000 Microsoft Corooration All rights reserved . 



[This is preliminary documentation and subject to change,] IS 

ISpGrammarBuilder::AddWordTransition 

ISpGrammarBuilderttAddWordTransition changes a phrase from the display form and adds each 
word individixally to the grammar. Inverse text normalization is preformed on he phrase before 
adding words to the grammar. 

HRESULT AddWordTransitionC 

S P S T ATEHA2!IDLE hFromS t a t e , 

SPSTATEHANDLE hToS ta te , 

const WCHAR *psz, 
const WCHAR *pszSeperators f 

S PGRAMMARWORDTYPE eWordType , 

fioat Weight, 
const SPPROPERTYINFO *pPropInfo 

); 

Parameters 

hFromState 

Handle of the "from" word transition state information. 
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Handle of the "from" word transition state information. 
hToState 

Handle of the "to" word transition state information. 

psz 

Address of a null-terminated string containing the transition information. If the value in psz is 
NULL, the contents of psz is an epsilon, 
pszSeperators 

Address of a null-terminated string containing the transition word separation characters, 
pszSeperators points to a single word if this value is NULL, or else pszSeperators specifies the 
valid separator characters. 
eWordType 

The SPGRAMMARWORDTYPE enumeration that specifies the grammar type. Currently, 
only valid SPWT_LEXICAL is supported. 
Weight 

Value specifying the granmiar rule weight information. 
pPropInfo 

The SPPROPERTYINFO structure containing property name and value infomiation that is 
associated with the grammar. 

Return values 



Value Description 

S_OK Function completed successfully. 

E_INVALID ARG At least one of psz, pszSeparators, or pPropInfo is invalid 

or bad. Altemately eWordType is a value other than 
SPWT_LEXICAL. 

F AILED(hr) Appropriate error message. 

Example 

The following code snippet illustrates the use of AddWordTransition. 

{ 

HRESULT hr = S_OK; 

SPSTATEHANDLE hStateHello; 
SPSTATEHANDLE hStateHellol ; 
SPSTATEHANDLE hStateBye; 
SPSTATEHANDLE hStateByel; 

TEST_TOPIC = "Add word transition from normal state to NULL state (end of rule 

//=. = = = = = ~ = = = = = = = = = = = = = = = = = =: = = = = ^ = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 

// define a new rule whose initial state is hState 

if (s_fVerifyEmptyRule) 

hr = pGrammarBuilder->Commit (0) ; 
//Check return value 

} 

// add a word transition from hStateHello to NULL 

hr = pGrammarBuilder->AddWordTransition (hStateHello, NULL, L"Hello", L" ", SPW 
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//Check return value 

hr = pGrammarBuilder->Commit (0) ; 
//Check return value 

TEST__TOPIC = "Add word transition from a 'fly* state which is not connected to 

= = = = = . = _ = = = = . = = = = = = . = = = = = = = = = = = = = = = = = = = = = = = = = 

SPSTATEHANDLE hStateFly; 

hr = pGrammarBuilder->AddWordTransition (hStateFly, NULL, L"fly", NULL, SPWT_LE 
//Check return value 

if (s_fVerifyFlyState) 

hr = pGramtnarBuilder->ComTnit (0) ; 
//Check return value 

} 

// = = = = ™. = = = = = =. = = = = = = ^^ = = = = = ™ = = = ^ = = = = = = = = = = = = = =: = = = = = = = = = = = = ™ = = = ^ 

TEST_TOPIC - "Add word transition to non-NULL state"; 

if (s_fVerifyEmptyRule) 

hr = pGrammarBuilder->Commit (0) ; 
//Check return value 

} 

// add word transitions from hStateBye to hStateByel then to NULL 

hr = pGrammarBuilder->AddWordTransit ion (hStateBye, hStateByel, L"Good", L" ", 

//Check return value 

hr = pGrammarBuilder->AddWordTransition (hStateByel, NULL, L"bye", L" SPWT_L 
//Check return value 

hr = pGrammarBuilder->Commit (0) ; 

CheckHr(hr, tpr, CatMsg (TEST_TOPIC, ": Commit (0) ")) ; 

TEST_TOPIC = "Add additional word transition to a node"; 

^ ^ hr = pGrammarBuilder->AddWordTransition(hStateHello, NULL, L"Hi", L" ", SPWT_L 
//Check return value 

hr = pGrammarBuilder->Commit (0) ; 
//Check return value 

TEST_TOPIC - "Add duplicate word transition to a different node"; 
// add duplicate word transition from hStateHello to newNode 

hr = pGrammarBuilder->AddWordTransition (hStateHello, hStateHellol, L"Hi", L" " 
//Check return value 

hr = pGrammarBuilder->Commit (0) ; 
//Check return value 

// now finish this rule 

hr - pGrammarBuilder->AddWordTransition (hStateHellol, NULL, L"there", L" SP 
//Check return value 

hr = pGrammarBuilder->Commit (0) ; 
//Check return value 

TEST_TOPIC - "Add duplicate word transition to the same NULL node"; 

hr = pGrammarBuilder->AddWordTransition (hStateHello, NULL, L"Hi", L" ", SPWT_L 
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//Check return value 

//__^_____.__==._=__=._=™===..==..============.=.==.===== 

TEST__TOPIC = "Add duplicate word transition to the same non-NULL node" ; 

^ ^ hr - pGramTnarBuilder->AddWordTransition(hStateHello, hStateHellol , L"Hi", L" " 
//Check return value 

© ^ 995:200p_ MjcrosoftCwppratipn All ri^ts reserved. 

[This is preliminaiy documentation and subject to change.] ^1 

ISpGrainmarBuilder::AddRuleTransition 

HRESULT AddRuleTransition( 

S P STATEHANDLE hFromSta t e , 

SP STATEHANDLE hToS tate, 

SP STATEHANDLE hRul e , 

float ^eigJit, 
const SPPROPERTYINFO *pPropInfo 

); 

Parameters 

hFromState 

Handle of the "from" rule transition state information. 
hToState 

Handle of the "to" rule transition state information. 

hRuIe 

Handle of the grammar rule's initial state. 

Weight 

Value specifying the grammar rule weight information. 
pPropInfo 

The SPPROPERTYINFO structure containing property name and value information associated 
v^th the grammar. 

Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG The grammar nodes rule state are the not the same. 

E_OUTOFMEMORY Not enough memory to complete operation. 

FAILED(hr) Appropriate error message. 

©1995-2000 Microsoft Corporation All rights^ resented 

[This is preliminary documentation and subject to change.] 

ISpGrammarBuilder : : AddResource 
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ISpGrammarBuilder: : AddResource 

HRESULT AddResource ( 

SPSTATEHANDLE hRul eSta te, 
const WCHAR *pszResourceName , 
const WCHAR *pszResourceValue 

); 

Parameters 

hRuleState 

[in] Handle of the rule state information. 
pszResourceName 

[in] Address of a null-terminated string specifying the resource name information. 

pszResource Value 

[in] Address of a null-terminated string specifying the resource value information. 
Return values 

Value Description 

S OK Function completed successfully. 

FAILED(hr) Appropriate error message. 

Example 

The following code snippet illustrates the use of AddResource. 

{ 

HRESUIiT hr = S_OK; 
int tpr = TPR_PASS; 

SPSTATEHANDLE hinit; 

DOCHECKHREX(hr = pGraTnmarBuilder->GetRule(L"rulel", 1, 0, TRUE, &hlnit);); 
SPSTATEHANDLE hState; 

DOCHECKHREX{hr pGrammarBuilder- >CreateNewState (hInit , &hState);); 
TEST__TOPIC = "AddResource using the hInxtState"; 

hr = pGrammarBuilder->AddResource(hInit, L"ResNamel" , L"ResValuel") ; 
CheckHr{hr, tpr, TEST__TOPIC) ; 

TEST_TOPIC = "AddResource using hState 1= hInit"; 

hr = pGrammarBuilder->AddResource (hState, L"ResName2", L"ResValue2 " ) ; 
CheckHr(hr, tpr, TEST_TOPIC) ; 



return tpr; 

) 



© 1995:2000 Microsoft Cp_ipoiution_ AUji£^ts reserved. 



[This is preliminaiy documentation and subject to ckiiige.] 

ISpGrammarBuilder: rCommit 
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ISpGrammarBuilder : rCommit 

ISpGrammarBuilder : : Commit 

HRESULT Commit ( 

DWORD dwReserved 

); 

Parameters 

dwReserved 

Reserved. 

Return values 

Value Description 

S OK Function completed successfully. 

FAILED(hr) Appropriate error message. 

Example 

The following code snippet illustrates the use of Commit. 

{ 

HRESULT hr = S_OK; 
int tpr = TPR_PASS; 

TEST_TOPIC = "Commit when there are no rules"; 

hr = pGrammarBuilder->Commit (0) ; 

CompareHr (hr, SPERR__lsrO_RULES , tpr, TEST_TOPIC) ; 

// not add some rules 

DOCHECKHREX(hr = pGrammarBuilder- >GetRule (L"rulel" , 1, SPRAF_Dynamic, TRUE, NU 
SPSTATEHANDLE hState; 

DOCHECKHREX(hr = pGrammarBuilder- >GetRule(L"rule2", 2, 0, TRUE, &hState);); 
DOCHECKHREX(hr = pGrammarBuilder- >AddWordTrans it ion (hS tat e , NULL, L"test", L" 

//=========================™============-=====-=— ===-=======-===- 

TEST_TOPIC = "Commit normally"; 

hr = pGrammarBuilder- >Commit (0) ; 
CheckHr(hr, tpr, TEST_TOPIC) ; 

} 

return tpr; 

} 

Related topics 

© 1995-2000 Microsoft Corporation. All rights reserved 

Microsoft Speech SDK ^-v^^ 
with SAPI 5.0 m 
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[This is preliminaiy documentation and subject to change.] 

Lexicon Manager 

The following section covers: 



• ISpContainerLexicon 

• ISpLexicon 

• ISpPhoneConYerte 



Microsoft Speech SDK 



©1995-2000 Microsoft Corporation, AU rights res_erved. 



with SAPI 5.0 I® 

[This is preliminary documentation aiid subject to change.l 

ISpContainerLexicon 

ISpContainerLexicon inherits from ISjpLexicon. 
Methods in Viable Order 

ISpContainerLexicon Methods Description 

AddLexicon Adds a lexicon and its type to the lexicon stack. 

© 1995-2000 Microsoft_Corporat]pn.„Ai! ri^ts reserved. 



[This is preliminmy docxBTieatation and subject to change.] 

ISpContainerLexicon: : AddLexicon 

ISpContainerLexicon:: AddLexicon adds a lexicon and its type to the lexicon stack. 

HRESULT AddLexicon ( 

I SpLexicon *pAddLexl con , 
DWORD " dwFlags 

); 

Parameters 

pAddLexicon 

[in] Pointer to the lexicon interface. 
dwFlags 

[in] flags of type SPLEXICONTYPE indicating the lexicon type. 
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Return values 



Value 

S_OK 

E_INVALIDARG 
E„POINTER 
E_OUTOFMEMORY 
FAILED(hr) 



Description 

Function completed successfully. 
dwFlag is invalid or bad, 
pLexicon is invalid or bad. 
Exceeded available memory. 
Appropriate error message. 



© 1995-2000 Microsoft Corporation Ail rights reserved 



Microsoft Speech SDK 
with SAPI 5.0 




[This is prcliminai-y documentation and subject to change.] 



ISpLexicon 



The Lexicon database is a repository of words and word-related information such as pronunciations 
and parts of speech. The SAPI lexicon interface provides application CSR and TTS engine 
developers a standard method with which to create, access, modify, and synchronize with lexicons. 

There are two types of custom lexicons supported by lexicon interface: user and application. The user 
lexicon stores words specific to a user. It is a read/write lexicon and is shared among all applications. 
The appUcation lexicon is supplied by the application and stores words specific to the application. 
The application supplied lexicons are read-only. AppUcation lexicons ensure that the vocabulary used 
by the application is well represented in the lexicon. 

AppUcation lexicons are buiU with an appUcation lexicon compiler shipped wAh. the SDK (not 
shipped in beta release). The lexicon interface provides methods to synchronize changes in lexicons 
using a lexicon generation ID. These changes in the lexicon are a resuh of modifications to user 
lexicons or for the installation or uninstallation of application lexicons. CUents can use the 
synchronization to update their private stores with the changes made to the custom lexicons while the 
client has been offline. For example, SR engines can update their language models with changes 
made to the custom lexicons while the SR engine had been off-Une. 

Note: Application lexicons cannot be added in the runtime environment. 
When an application wants to add a lexicon, the appUcation must either: 

1 . Create and add a private lexicon. 

2 . Register the lexicon, close the container lexicon and restart it. 

Apart from custom lexicons, the lexicon interface provides access to vendor, morph, and letter-to- 
sound lexicons that Microsoft ships with SAPI. Vendor lexicons are large vocabulary lexicons 
holding words and their pronunciations and parts of speech. The morph lexicons derive 
pronunciations using the data in the vendor lexicon. The letter-to-sound lexicon computes the 
pronunciation of a word fi-om its speUing. 

Methods in Viable Order 

ISpLexicon Methods Description 
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GetPronunciations Gets pronunciations and parts of speech for a word. 

AddPronunciation Adds pronunciations and parts of speech to a word. 

RemovePronunciation Removes the word and its pronunciations and the parts of 

speech from the user lexicon. 

GetGeneration Passes back the generation ID for a word. 

GetGenerationChange Gets a list of words which have changed between the 

current and a specified generation. 

GetWords Gets all words for the user and/or appUcation lexicons. 

© 1 995-2000 Microsoft CorporatipB^M 



[This is preliminar}'^ documentation and subject to change.] 

ISpLexicon: : GetPronunciations 

ISpLexicon::GetPronunciations gets pronunciations and parts of speech for a word. 

HRESULT GetPronunciations { 

const WCHAR *pszWord, 
LANGID LanglD, 
DWORD dwFlags , 

SPWORDPRONUNCIATIONLI ST ^pVJordProxiunci a tionLi s t 

); 

Parameters 

pszWord 

[in] Pointer to a text string as a search keyword. Length must be equal to less than 
SP_MAX_WORD_LENGTH. 
LangID 

[in] The language ID of the word. May be zero to indicate that the word can be of any 
LANGID. 
dwFlags 

[in] Bitwise flags of type SPLEXICONTYPE indicating that the lexicons searched for this 
word. 

pWordPronunciationList 

[in, out] Pointer to SPWORDPRPNUNCIATIONLIST structure in which the pronunciations 
and parts of speech are returned. 

Return values 

Value Description 

S_OK Function completed successfully. 

E^POINTER Either pszWord and/or 

pWordPronunciationList is NULL. 

E_INVALIDARG Either pszWord and/or 

pWordPronunciationList is invalid or bad. 

E_OUTOFMEMORY Exceeded available memory. 

SPERR UNINITIALIZED Interface not allocated. 
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SPERR NOT_IN_LEX Word is not found in the lexicon. 

SP_WORD_EXISTS_WITHOUT_PRONUNCIATION The word exists but does not have a 

pronunciation. 

FAILED(hr) Appropriate error message. 

Example 

The following example is a code fragment demonstrating the use of GetPronunciations. 

SPWORDPRONUNCIATIONLIST spwordpronlist ; 

memset (&spwordpronlist , 0, sizeof (spwordpronlist) ) ; 

hr = pISpLexicon->GetPronunciations{L"resume", 1033, eLEXTYE__ALL , &spwordp 

//test for results 

if ( I SUCCEDED (hr) ) return; 

for ( . ^ 

SPWORDPRONUNCIATION pwordpron = pwordpronlist->pFirstWordPron; 

wordpron != NULL; 

wordpron - pwordpron- >pNextWordPr on 
) 

^ DoSomethingWith (pwordpron- >ePartOf Speech, pwordpron- >szPronTinciation) ; 
} 



//free all the buffers 

CoTaskMemFree (spwordpronlist .pvBuffer) ; 



> l_991-2000^_tcroAofLCorppmtlp^ All^ri^hts resen'ed. 



[This is preiiminary documentation and subject to change,] IS 

ISpLexicon: : AddPronunciation 

ISpLexicon::AddPronunciation adds word pronunciations and parts of speech (POS) to the user 
lexicon. SAPI will not modify the word if spelling, pronunciation, and POS are the same as the 
existing entry. 

HRESULT AddPronunciation { 

const WCHAR *pszWord, 
LANGID Lang ID, 

SPPARTOFSPEECH ePartOf Speech, 
const WCHT^ *pszPronnnciation 

); 

Parameters 

pszWord 

[in] The word to add. 

LangID , jq ^^^^^ ^^^^ speech user default will be used if LANGID is omitted. 

Length must be equal to or less than SP_MAX_WORD_LENGTH. 
ePartOfSpeech 

[in] The part of speech of type SPPARTOFSPEECH. 
pszPronunciation 

[in] Null-terminated pronunciation of the word in the NUM phone set. Multiple pronunciations 
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[in] Null-terminated prontmciation of the word in the NUM phone set. Multiple pronunciations 
may be appended to a single word by assigning a new POS. The length must be equal to or less 
than SP_MAX__PRON_LENGTH. 

Return values 



Value 

S_OK 

E_POINTER 

E_INVALIDARG 

SP_ALREADY_IN_LEX 

SPERR_APPLEX_READ_ONLY 

SPERR^UNE^ITIALIZED 

E_OUTOFMEMORY 

FAILED(hr) 



Description 

Function completed successfully. 
Pointer to the word is invalid. 
At least one of the parameters are invalid or bad. 
Word has already been added to the lexicon. 
Word is read only and carmot be removed. 
The interface has not been initiaUzed. 
Exceeded available memory. 
Appropriate error message. 



Example 

The following is an example of AddPronunciation. 

WCHAR wszNum[3] ; 
wszNum[0] = OxOOOb; 
wszNumEl] = 0x0012; 
wszNum[2] = 0; 

pISpLexicon->AddPronunciation{L"Rob", 0x409, SPPS_NOUN, szNum) ; 

© 1995-2000 Microsoft Corporation All righte reserved. 



[This is preliminary documentation and subject to change.] 

ISpLexicon::RemovePronunciation 

ISpLexicon::ReinovePronunciation removes the word, its pronunciations and the part of speech 
(POS) from the user lexicon. 

HRESULT RemovePronunciation ( 

const WCHAR *pszWord, 
LANGID LangID, 
SPPARTOFSPEECH ePartOf Speech r 

const' WCHAR *psz Pronunciation 

); 

Parameters 

pszWord 

[in] The word to remove. 
LangID 

[in] The language ID of the word. The speech user default will be used if LANGID is omitted. 

ePartOfSpeech 
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[in] The part of speech of type SPPARTOFSPEECH. 
pszPronunciation 

[in] Pronunciation of the word. If the pronunciation is non-NULL, then delete only this 
pronunciation and its associated part of speech. If there is only one pronunciation, then delete 
the word. If the pronunciation is NULL, then delete the word and all of its pronunciations and 
parts of speech. 

Return values 

Value Description 

S OK Function completed successfully. 

E_POINTER Pointer to the word is invalid. 

E IN VALID ARG One of the parameters is not valid. 

E^OUTOFMEMORY Exceeded available memory. 

SPERR__NOT_IN_LEX Word is not found in the lexicon. 

SPERR_APPLEX__READ_ONLY Word is read only and can not be removed. 

SPERR_UNn^ITIALIZED Interface not initiaUzed. 

F AILED(hr) Appropriate error message. 

Example 

The following code fragment is an example of RemovePronunciation. 

WCHAR szPronounce [MAX_PRON_LEN] ; 
DWORD d; 

VOICEPARTOFSPEECH PCS ; 

HRESULT hr = Get ( (VOICECHARSET) 0 , pszText, wSense, szPronounce, MAX_PRON_L 
if (SUCCEEDED (hr) ) 

hr = mjpLex->ReTnovePronunciation(pszText, 1033, (SPPARTOFSPEECH) POS 

© 1995:2000 Microsoft Coo)oMipil--Mjigh^ie^^^^^ 



[This is preliminary documenlalion aiid subject to change,] 

ISpLexicon: :GetGeneration 

ISpLexicon::GetGeneration passes back the generation ID for a word. 

Each change (either as an install or uninstall) in the user lexicon will increment the generation ID by 
one. 

HRESULT GetGeneration( 

DWORD -^pd-wGeneration 

); 

Parameters 

pdwGeneration 
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pdwGeneration 

The generation ID. This is a relative count of how many times the custom lexicons have 
changed. 



Return values 



Value 

S_OK 

E_POINTER 
E_INVALIDARG 
SPERR_UNINITIALIZED 
FAILED(hr) 



Description 

Function completed successfully. 
Generation value is zero or undefined. 



Generation value is invalid. 
Interface is not initialized. 
Appropriate error message. 



© J995:2pOOMcrospft_Co]0Ppmtip^^^ AU rights reserved. 



[This is preliminary documentatioB and subject to change.] 




ISpLexicon: iGetGenerationChange 



ISpLexicon::GetGenerationChange passes back a list of words which has changed between a given 
generation and current generation. 

HRESULT GetGenerationChange ( 



SPWORDLIST -^pVJordList 

); 

Parameters 

dwFlags 

[in] The lexicon category of type SPLEXICONTYFE. Currently it must be eLEXTYPE_USER 
or eLEXTYPE_„APP. 
pdwGeneration 

[in, out] The generation ID of client when passed in. The current generation ID is passed back 
on successful completion of the call. 
pWordList 

[in, out] The buffer containing the word list and its related information. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_POINTER pdwGeneration is zero or NULL. 

E_IN V ALID ARG pdwGeneration is invalid or bad. 

SPERR UNINITIALIZED Interface has not been initialized. 

E OUTOFMEMORY Exceeded available memory. 

SP_LEX_NOTHING_TO_SYNC No words are available with which to synchronize. 
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SP__LEX__NOTHING_TO_SYNC No words are available with which to synchronize. 

SPERR_APPLEX_READ_ONLY Word is read only and cannot be removed. 

SPERR_LEX_VERY_OUT_OF_SYNC The value passed in with pdwGeneration is greater than 

the custom lexicon's generation ID. Use 
ISpLexicon: :GetWords if GetGenerationChange returns 
SPERR„LEX_„VERY_OUT_,OF_S YNC to regenerate an 
entire list of words based on the current generation. 

FAILED(hr) Appropriate error message. 

Example 

The following is an example of GetGenerationChange. 

MainSRLoop : 
for (;;) 

^ hr = plSpLexicon->GetGenerationChange(eLEXTYPE_USER, &m_dwGeneration, &spwordl 

// If, for example, a new application lexicon was added, we'll have 
//to rebuild from scratch, 
if (hr == SPERR_LEX_VERy_OUT_OF__SYNC) 
RebuildO; // Call GetWords 

// Some other error 
if (FAILED (hr) 

DealWithOtherErrors () ; 

// Loop thru the changed words, and their new pronunciations 
for (SPWORD *pword = spwordlist .pFirstWord; 
pword != NULL; 
pword = pword- >pNextWord) 

^ for (SPWORDPRON pwordpron = pword- >pFirstWordPron ; 
pwordpron != NULL; 

pwordpron = pwordpron- >pNextWordPr on) 

AddPronunciationToEngineDataStructures ( 
pword- >pszWord, 
pwordpron- >ePartOf Speech, 
pwordpron- >pszPronIPA) ; 



// Continue with SR code... 

© 1995-2000 Microsoft Corporation. All rights reserved . 



flTiis is preiiminar>^ documemation and subject to change,] 

ISpLexicon: : GetWords 

ISpLexicon: :GetWords gets all words for the container lexicons. 

This method is called repeatedly with the cookie (set to zero the first time) until S 
S FALSE is returned indicating additional information is left. 




OK is returned. 
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HRESULT GetWords( 

DWORD dwFlags, 
DWORD -^pdwCeneration, 
DWORD ^pdwCookie, 
S PWORDLI ST *pWordLi s t 



Parameters 

dwFlags ^ ^ . , 

[in] Bitwise flags of type SPLEXICONTYPE from which words are to be retneved. Valid 
values are eLEXTYPE^USER anTeLEXTO^ 

pdwGeneration 

[out] The current generation ID of the custom lexicon. 

pdwCookie ^ ^ ti i • 

[in, out] Cookie passed back by this call. It should subsequently be passed back m to get more 
data. If the call returns S_F AILED, then data is remaining and GetWords should be called 
again. The initial value of the cookie passed in must be zero or pdwCookie be a NULL pointer. 
NULL indicates the method should return all words contained in the lexicon. If it cannot 
SP_LEX_REQUIRES_COOKIE is returned instead. 

pWordList 

[in, out] The buffer containing the word list and its related information. 
Return values 



Value 

S_OK 

S_FALSE 

E__POINTER 

E_INVALIDARG 

E_OUTOFMEMORY 

SPERR_UNINITIALIZED 

SP_LEX_NOTHING__TO_SYNC 

SP_LEX_REQUIRES_COOKIE 

FAILED(hr) 



Description 

Function completed successfully. In addition, the value of 
pdwCookie did not change. 

Additional words are left in the lexicon(s) to process. The 
value of pdwCookie did change. 

At least one of pdwGeneration, pdwCookie, pWordList is 
zero or NULL. 

One of the parameters is not valid. 
Exceeded available memory. 
Interface not initialized. 

No words are available with which to synchronize* 

A complete list of words cannot be returned from the 
container lexicon, pdwCookie must not be NULL. 

Appropriate error message. 



Example 

The following is an example of using GetWords. 

SPWORDLIST spwordlist; 

memset (&spwordlist , 0, sizeof (spwordlist) ) ; 
dwCookie = 0 ; 

while (SUCCEEDED (hr = pISpLexicon- >GetWords (eLEXTYPE_USER | eLEXTYPE_APP , &dwG 

^ for (SPWORD *pword = spwordlist .pFirstWord; 
pword != NULL; 
pword - pword- >pNextWord) 

{ 
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} 



for (SPWORDPRONtJNCIATION *pwordpron = pword- >pFirstWordPronunciation; 
pwordpron ! = NULL ; 

pwordpron = pwordpron- >pNextWordPronunciation) 

^ DoSomethingWith (pwordpron- >ePartOf Speech, pwordpron- >pszPronI PA) ; 
} 



} 



if (hr == S_OK) 

break; // nothing more to retrieve 



//free all the buffers 
CoTaskMemFree (spwordlist .pvBuf f er) ; 

// Check for SUCCEEDED (hr) ; 



© 199_5:200p„MicrospfLCprppmtion._^ 
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[This is preliminan" documentation and subject to change.] 

ISpPhoneConverter 

The ISpPhoneConverter interface enables the cUent to convert from the SAPI character phoneset to 
the Id phoneset. 

When to Use 

Call methods of the ISpPhoneConverter interface to convert between character and NUM phonesets. 
Note: ISpPhoneConverter inherits from ISpObjectWithToken. 
Methods in Vtable Order 



ISpPhoneConverter Methods 

PhpneToId 

IdToPhone 



Description 

Converts an internal phone string to Id code string. 
Converts an Id code string to internal phone. 

© 1995-2p_00 Microsoft Corporation Alljigjits re_served 



[This is preiiminaiy documentation and subject to change.] 

ISpPhoneConverter: :PhoneToId 

ISpPhoneConverter: rPhoneToId converts an internal phone string to Id code string. 
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The internal phones are space separated and may have a space at the end. 

HRESULT PhoneToIdC 

const WCHAR *pszPhone, 
SPPHONEID *pXd 

); 

Parameters 

pszPhone . . x- 

[in] Address of a null-terminated string that contains the phone stnng miormation. 

[out] Address of the SPPHONEID that receives the phone identifier. 
Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG One or more argxmients are invalid. 

FAILED(hr) Appropriate error message. 



' 1995-20PP Microsoft CqrEptut]pn._An rights reserved. 



[This is preiiminaiT documentation and subject to change.] 

ISpPhoneConverter : :IdToPhone 

ISpPhoneConverter::IdToPhone converts an Id code string to internal phone. 
The output internal phones are space separated. 



HRESULT IdToPhone( 

const SPPHONEID *pJd, 
WCHAR *pszPhone 

); 

Parameters 

pid 

[in] Address of the SPPHONEID that contains the phone identifier. 

pszPhone . , , . • r. ^• 

[out] Address of a null-terminated string that receives the phone stnng mtormation. 

Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG One or more arguments are invalid. 

E POINTER Invalid pointer. 
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FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation. AU rights resen'ed 

Microsoft Speech SDK , 
with SAPI 5.0 ^ 

ffhis is preliminar>^ documentation and subject to change,] 

Resource Manager 

The following section covers: 

ISpDataKey 
ISpRegDataKey 
ISppbiectTpkenlnit 
rSpObjectTokenCa^^^ 
ISpObjectToken 
lEnumSpObj ectTokens 
ISpObjectWithTpk^^^^ 
ISpResourceManager 
"iSpTask " " " 
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[This is preiiminaty dociiiiientarion and subject to change.] 

ISpDataKey 

The ISpDataKey interface is used to access the speech object registry functions. 
When to Implement 

Implement this interface when a caller wants to have access and the ability to modify the registry 
information for a given speech object. 

Methods in Vtable Order 

ISpDataKey Methods Description 

SetData Sets the value information for a specified registry key. 

GetData Retrieves a value information from a specified registry 

key. 

SetStringValue Sets the string value information for a specified registry 

key. 

GetStringyalue Retrieves the string value information from a specified 

registry key. 

SetDWORD Sets the value information for a specified registry key. 
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GetDWORD 


ivetncves uie vaiue iniorniauon ironi a bpcciiicu icgiMi^/' 




key. 




Opens a specified registry key. 


CreateKey 


Creates a new registry key. 


DeleteKey 




DeleteValue 


Deletes a namea value irom tne speciiiea registry Key. 


EnumKeys 


Enumerates the subkeys of the specified open registry 


key. 


EnumValues 


Enumerates the values of the specified open registry key. 



© 1995-2000 Microsoft Corporation All rights reserved 
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[This is preliminary documentation and subject to change.] 

ISpDataKey : : SetData 

ISpDataKey::SetData sets the value information for a specified registry key. 

HRESULT SetData { 

const WCHAR *pszValueName, 
UL0N6 cbData, 
const BYTE *pData 

) ; 

Parameters 

psz Value NctTHC 

[in] Address of a null-terminated string that contains the registry key value name. 

cbData . i * j> 

[in] Size of the destination data buffer that contains the registry key value mtormation. 

pData . 1 - n 

[out] Address of the destination data buffer that contains the registry key value information. 

Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG ^iXhQX pszValueName or pData is an invalid or bad pointer. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Micrp_soft_Con>oration, All rig^ 
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ISpDataKey: :GetData 
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ISpDataKey::GetData 

ISpDataKey::GetData retrieves the value information from a specified registry key. 

HRESULT GetData( 

const WCHAR *pszValueNamer 
ULONG *pcbDa ta , 

BYTE *pData 

); 

Parameters 

psz Vctluc NciiTic 

Address of a null-terminated string containing the name of the registry key from which to 

retrieve the registry key value. 

pcbData , . i i 

Address of the size of the destination data buffer that receives the registry key value 

information. 

pData ^ 1 * r. 

Address of the destination data buffer that receives the registry key value information. 

Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG p^zFa/weA^ame is invalid or bad. 

E POINTER Either pcbData or pData is an invalid or bad pointer. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Cpippration.„AU/i^hts reserv-ed 



[This is prcliminarj^ documentation and subject to change.] W 

ISpDataKey : : SetStringValue 

ISpDataKey::SetStringValue writes the string value information for a specified registry key. 

HRESULT SetStringValue ( 

const WCHAR *pszValueName, 
const WCHAR ^pszValue 

); 

Parameters 

psz Value Naffie 

Address of the null-terminated string that specifies the name of the string value. If NULL, the 
default value of the registry key is used. 

pszValuc 

Address of a null-terminated string that contains the string value to be set for the specified key. 
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Address of a null-terminated string that contains the string value to be set for the specified key. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG Either pszValueName or pszValue is invalid or bad. 

FAILED(hr) Appropriate error message. 

© l_995^2000 Microsoft Cpji)prad^^ rights reserv-ed. 



[This is preliminary documentation and subject to change.] IS 

ISpDataKey : : GetStringValue 

ISpDataKey::GetStringValue reads the string value information from a specified registry key. 

HRESULT GetStringValue ( 

const WCHAR *pszVa.lueName , 
WCHAR **ppszValue 

); 

Parameters 

psz Value Nqth0 

Address of a null-terminated string that specifies the name of the registry key. If NULL, the 
default value of the registry key is read. 
ppszValue 

Address of a pointer to a null-terminated string that receives the string value for the specified 
key. 

Return values 

Value Description 

S OK Function completed successMly. 

E_rNfVALIDARG pszValueName is invalid or bad. 

E_POINTER ppszValue is invalid or bad. 

SPERR_N0T_F01JND Registry file not found. 

FAILED(hr) Appropriate error message. 

©1995-2000 Microso ft C orporation AJlrights reserved 
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ISpDataKey: : SetDWORD 



file://C:\WIND0WS\TEMP\~hh2B 1 B.htm 



12/28/00 



Application-Level Interfaces 



Page 81 of 199 



ISpDataKey::SetDWORD sets the specified DWORD to the registry. 

HRESULT SetDWORD( 

const WCHAR *pszValueName, 
DWORD dwValue 

); 

Parameters 

pszValueName 

Address of a null-terminated string that contains the registry key value name. 
dwValue 

Address of the destination data buffer that contains the registry key value information. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG pszValueName is invalid or bad. 

FAILED(hr) Appropriate error message. 

©1995-2000 Microsoft Corporation. _AU rights. reserved 



[This is preliminary documentation and subject to change.] 

ISpDataKey: :GetDWORD 

ISpDataKey::GetDWORD reads the specified DWORD from the registry. 

HRESULT GetDWORD{ 

const WCHAR * pszValueName , 
DWORD *pdwValue 

); 

Parameters 

psz Val ue Nain e 

[in] Address of a null-terminated string containing the name of the registry key from which to 
retrieve the registry key value. 
pdwValue 

[out] Address of the destination data buffer that receives the registry key value information. 
Return values 

Value Description 

S OK Function completed successfully, 

E INVALID ARG pszValueName is invahd or bad. 
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E_POINTER pdwValue is invalid or bad. 

SPERR_NOT_FOUND Registry key not found. 

F AILED(hr) Appropriate error message. 



© 1995-2000 Microsoft Corporation. AH rights reserved . 
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ISpDataKey : :OpenKey 



ISpDataKey::OpeiiKey opens a subkey and passes back a nev^ object that supports ISpDataKey for 
the specified subkey. 

HRESTJLT OpenKey( 

const WCHAR -^pszeuhKeyName, 
I SpDa t aKe Y * ^ppSuhKey 

); 

Parameters 

pszSubKeyName 

Address of a null-terminated string specifying the name of the key to open. 

ppSubKey 

Address of a pointer to an ISpDataKey interface, dl 
Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG pszSubKeyName is mydXid ox hdd, 

E POINTER ppSubKey is invalid or bad. 

SPERR_N0T_F01JND Registry key not found. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation. All rights reser\^ed . 



[This is preliminary docimientation and subject to change.] 

ISpDataKey: : CreateKey 

ISpDataKey::CreateKey creates a sub-key and returns a new object which supports 
ISpDataKey for the specified sub-key. 



HRESULT CreateKey { 

const WCHAR ^pszSubKey, 
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ISpDataKey **ppSuhKey 

) ; 

Parameters 

pszSubKey 

Address of a null-terminated string specifying the name of the key to create. 
ppSubKey 

Address of a pointer to an ISpDataKey interface. 
Return values 

Value Description 

S_OK Function completed successfixlly. 

E_INVALIDARG Either pszSubKeyName or ppSubKey is invalid or bad. 

FAILED(hr) Appropriate error message. 



ISpDataKey: :DeleteKey deletes a specified registry key and all its descendants. 
The function will remove the key and all of the key's values from the registry. 

HRESULT DeleteKey{ 

const WCHAR *pszSubKey 

); 

Parameters 

pszSubKey 

Address of a null-terminated string specifying the name of the key to delete. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG pszSubKeyName is invalid or bad. 

FAILED(hr) Appropriate error message. 



© 1995^2000 Microsoft Corporation All rights reserved. 
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ISpDataKey: :DeleteKey 



© 1995-2000 Microsoft Corporation All rights reserved 
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IB 
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ISpDataKey : :DeIete Value 



ISpDataKey::DeleteValue deletes a named value from the specified registry key. 

HRESULT DeleteValue( 

const WCHAR *pszValueName 

)? 

Parameters 

pszValueName 

Address of a null-terminated string specifying the value to be deleted. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG pszValueName is invalid or bad. 

SPERR_NOT_FOlJND Registry key not found. 

FAILED(hr) Appropriate error message. 



ISpDataKey: :EnumKeys enumerates the subkeys of the specified open registry key using the 
index. 



WCHAR * ■f'ppszKeyName 

) ; 

Parameters 



[in] Index of the subkey to retrieve. This parameter should be zero for the first call and 
incremented for subsequent calls. 
ppszKeyName 



©1995-2000 Microsoft Con)prat)on,AUii^ht^^ reserved. 
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ISpDataKey: :EnumKeys 



HRESULT EnumKeys ( 
UIiONG Index, 
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ppszKeyName 

[out] Address of a pointer to a null-terminated string that receives the enumerated key 
name. This must be freed with CoMemTaskFreeQ when no longer required. 

Return values 



Value 

S_OK 

E_INVALIDARG 
SPERR_N0T_F01JND 
E_OUTOFMEMORY 
FAILED(hr) 



Description 

Function completed successfully, 
ppszKeyName is invalid or bad. 
Registry key not found. 
Not enough memory to allocate string. 
Appropriate error message. 



© 1 995-200_0 Microsoft CorporatiQn_ AU rightsreserved 



[lliis is preliminary docmnentation and subject to change.] 

ISpDataKey : :Enuin Values 

ISpDataKey::EnumValues enumerates the values of the specified open registry key. 



HRESULT EniimValues ( 
ULONG Index, 
WCHAR '^'i'ppszValueName 

); 

Parameters 

Index 

Index of the subkey to retrieve. This parameter should be zero for the first call and 
incremented for subsequent calls. 
ppszVcilue NcifTie 

Address of a pointer to a null-terminated string that receives the enumerated registry key 
values. This must be freed with CoMemTaskFreeQ when no longer required. 



Return values 

Value 

S_OK 

E_INVALIDARG 
SPERR_NOT_FOUND 
E^OUTOFMEMORY 
FAILED(hr) 



Description 

Function completed successfully. 
ppszValueName is invalid or bad. 
Registry key not found. 
Not enough memory to allocate string. 
Appropriate error message. 



©1995-2000 Microsoft Corporation. AU rightsjeserved 



Microsoft Speech SDK 



file://C:\WIND0WS\TEMP\^hh2BlB.htm 



12/28/00 



Application-Level Interfaces 



Page 86 of 199 



Microsoft Speech SDK 
with SAPI 5.0 




[This is preliminary docmiientation and subject to change.] 



ISpRegDataKey 



The ISpRegDataKey inherits from ISpDataKey . 



Methods in Vtable Order 



ISpRegDataKey Methods 
SetKey 



Description 

Sets the hive registry key (HKEY) to use for 
subsequent token operations. 
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ISpRegDataKey: : SetKey 



ISpRegDataKey::SetKey sets the hive registry key (HKEY) to use for subsequent token 
operations. 

HRESULT SetKey ( 
HKEY hkey, 
BOOL fReadOnly 

) ; 

Parameters 

hkey 

[in] The registry key to use. 

fReadOnly ^ . . j i 

[in] Boolean flag setting the keys to read/write status. If TRUE, the registry is read only; 

FALSE sets it to read and write. 
Return values 

Value Description 

S OK Function completed successfully. 

SPERR_ALREADY_INITIALIZED Interface is already initialized. 

Example 

The following code snippet adds, tests and deletes a superfluous key from the speech registry. 
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HRESULT hr; 

CComPtr cpSpRegDataKey; 
CComPtr cpSpCreatedDataKey; 
CComPtr cpSpCategory; 
CComPtr cpSpDataKey; 
HKEY hkey; 

//create a bogus key under Voices 

hr = g_Unicode.RegCreateKeyEx{HKEY_LOCAL_MACHINE, 

L"SOFTWARE\\Microsoft\\Speech\\Voices\\bogus 

0, NULL, 0, KEY_READ | KEY__WRITE, NULL, &hkey, NULL); 

//Check error 

hr = CpSpRegDataKey. CoCreate Ins t ance (CLSID_SpDataKey) ; 
//Check error 

hr = CpSpRegDataKey- >SetKey (hkey, false); 
//Check error 

hkey = NULL; 

hr = CpSpRegDataKey- >QueryInterf ace ( &cpSpCreatedDataKey) ; 
//Check error 

//delete this bogus key 

hr = SpGetCategoryFromId(SPCAT_VOICES, ScpSpCategory) ; 
//Check error 

hr = cpSpCategory- >GetDataKey(SPDKL_LocalMachine, &cpSpDataKey) ; 
//Check error 

hr = cpSpDataKey->DeleteKey (L"bogus") ; 
/ /Check error 



© 1995-2000 Microsoft Corporation. AW rights reserved 
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[This is preliminary documentation and subject to change.) 

ISpObjectTokenlnit 

This interface inherits from ISpObjectToken. 
Methods in Viable Order 

ISpOb j ectTokenlnit Methods Description 

InitFromDataKey Initializes a token to use a specified datakey. 

© 1995-2000 Microsoft Corporation. All rights reserved 
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ISpObjectTokenInit::InitFromDataKey 
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ISpObjectTokenInit::SetObjectToken initializes a token to use a specified datakey. 

Dynamic token enumerators can use this to create tokens under their token enumerator's token. 
Once created, this enables ISpDataKey: :CreateKey to make a new data key, create a new object 
token, and then use InitFromDataKey, 



HRESULT InitFromDataKey ( 

const WCHAR *pszCategoryId, 
const WCHAR *pszTokenId, 
I SpDa t aKey *pDa taKey 

); 

Parameters 

pszCategoryld . 

[in] Address of an ISpDataKey interface that specifies the system registry key from 

which to create the token. 
pszTokenId 

[in] The null-terminated string name of the Tokenid used as the default. 
pDataKey . 

[in] Address of an ISpDataKey interface that specifies the system registry key from 
which to create the token. 

Return values 

Value Description 

S OK Function completed successfully. 

E POINTER At least one of the parameters is invalid or bad. 
SPERR_ALREADY_INITIALIZED Token is already initialized. 

SPERR_TOKEN_DELETED Key has been deleted. 

E_OUTOFMEMORY Exceeded available memory. 

© 1995-2000 Microsoft Corporation. All rights reser\^e4 . 

Microsoft Speech SDK ti^, 
with SAPI 5.0 W 

[His is preliminar}^ documentation and subject to change.] 

ISpObj ectTokenCategory 

The ISpObjectTpken interface sets object token entries into the registry. 

In general, attributes are null-terminated strings comprising a series of key:defmition 
relationships. For example, a token may be defined as: 

"vendor=microsoft;language=409;emptyflag=;someflag;..." 
In this instance. 
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• "vendor=microsoft" means a string exists under TokenID\attributes with name vendor 
and value "microsoft"; 

• "emptyflag=" means a string exists under TokenID\attributes with name emptyflag and 
value ""; 

• "someflag" means a string exists under TokenID\attributes with name someflag and any 
value. 



ISpObjectTokenCategory inherits from ISpDataKey . 
Methods in Vtable Order 

ISpObjectToken Methods 
Setid 
Getid 

GetPataKcy 
EmimTokeiis 
SetDefaultTokenld 
GetDefaultTokerf^^ 

PA 995-2000 Mjcrosoft„Corpom^^^ ^j] jMts„reseryed. 



Description 

Sets the Categoryld 
Retrieves the Categoryld. 

Gets the data key associated with a specific location. 
Enumerates the tokens for the category. 
Sets a specific Tokenid as the default for the category. 
Retrieves the defauh Tokenid for the category. 



[This is preliminary documentation and subject to change.] '^S 

ISpObjectTokenCategory::SetId 

ISpObjectTokenCategory: :SetId sets the Categoryld. 
This may be called only once. 



HRESULT Setld( 

const WCHAR *pszCategoryld, 
BOOL fCrea telfNotExist 

) ; 



Parameters 

pszCategoryld 

[in] The null-terminated string name of category to set. 
fCreateljNotExist . . 

[in] An optional parameter allov^ing the object to be created if not currently existing. 

default is FALSE unless otherwise specified. 

Return values 



Value Description 

S OK Function completed successfully. 

SPERR_ALREAD Y_INITIALIZED Category interface is already initialized. 
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E_INVALIDARG 
FAILED(hr) 



pszCategoryld is invalid or bad. 
Appropriate error message. 



Notes 

Category IDs be be in the following form. 

"HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVer^ 

Speech\Recognizers" 

The only acceptable HKEYs are: 

HKEY_CLASSES_ROOT 

HKEY_CURRENT__USER 

HKEY_LOCAL_MACHINE 

HKEY_CURRENT_CONFIG 

Examples 

The following snippet creates an new category and sets the ID. The code also shows the 
required steps for removing a category. 

HRESULT hr; 

CComPtr cpSpCategory; 
CComPtr cpSpRegDataKey; 
HKEY hkey; 

hr = cpSpCategory. CoCreatelnstance (CLSID_SpObjectTokenCategory) ; 
//Check return code 

hr - cpSpCategory- >SetId(L"HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\S 
//Check return code 

//delete this bogus category 

hr = g_Unicode.RegOpenKeyEx(HKEY_LOCAL_iyiACHINE, 

L"SOFTWARE\\Microsoft\\Speech" , 

0, KEY_READ j KEY__WRITE, &hkey) ; 
//Check return code 

hr = cpSpRegDataKey.CoCreateInstance{CLSID_SpDataKey) ; 
//Check return code 

hr = CpSpRegDataKey- >SetKey (hkey, false) ; 
//Check return code 

hr = cpSpRegDataKey->DeleteKey(L"bogus") ; 
//Check return code 



©_ 1 995-2_000 Microsoft Cpippxation _A1J rights reserved 
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[This is preliminary docunientation and subject to change.] 




ISpObjectTokenCategory : :GetId 



ISpObjectTokenCategoiy::GetId retrieves the category ID. 

HRESULT GetldC 

WCHAR * *ppszCoMemCa tegoryld 

); 

Parameters 

ppszCoMemCategoryld 

[in] The null-terminated string name of the current category. ppszCoMemC 
must be freed when no longer required. 

Return values 

Value Description 

S OK Function completed successfully. 

SPERR_IJNINITIALIZED Category interface is not initialized. 

E POINTER ppszCoMemCategoryld is invalid or bad. 

FAILED(hr) Appropriate error message. 

Example 

The following snippet retrieves Categoryld for SPCAT__VOICES. 



HRESULT hr; 

CComPtr cpSpCategory; 
CSpCoTaskMemPtr cpwszOldID; 

hr = SpGetCategoryFromId(SPCAT_VOICES, &cpSpCategory) ; 
//Check return code 

hr = cpSpCategory- >Get Id ( &cpwsz01dID) ; 
//Check return code 



ISpObjectTokenCategory::GetDataKey 



©1995-200pjvlicrosoft Corporation rights reserved 
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ISpObjectTokenCategoiy::GetDataKey gets the data key associated with a specific location. 



HRESULT GetDataKey( 

SPDATAKEYIiOCATION spdkl , 
ISpDataKey * *ppDa taKey 

); 

Parameters 

spdkl 

[in] The registry's top-level node to be searched. 
ppDataKey 

[out] The data key interface associated with the location spdkl. 
Return values 

Value Description 

S OK Function completed successfully. 

SPERR_UNINITIALIZED Data key interface is not initialized. 

E_POINTER ppDataKey is invalid or bad. 

FAlLED(hr) Appropriate error message. 

Example 

The following snippet retrieves the data key associated with the local machine registry for 
SPCAT_V01CES. 

HRESULT hr; 

CComPtr cpSpCategory; 
CComPtr cpSpDataKey; 

^ SpGetCategoryFromId(SPCAT_VOICES, &cpSpCategory) ; 
//Check return code 

hr = cpSpCategory- >GetDataKey(SPDKL_LocalMachine, &cpSpDataKey) ; 
//Check return code 

© 1 995-2000 Microsoft Corporation. All rights reser\'ed 
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ISpObjectTokenCategory::EnumTokens 



Sii- \ 
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ISpObjectTokenCategoryxEnumTokens enumerates the tokens for the category by 
attempting to match specified requirements* 

HRESULT EnumTokens( 

const WCHAR *pszReqAttribs , 

const WCHAR *pszOptAttribs , 

lEnumSpOb j ec tTokens * *ppEnum 

); 

Parameters 

pszReqAttribs 

[in] The string of required attributes for the token. 

pszOptAttrihs , . . , i 

[in] The string of optional attributes for the token. The order m which the tokens are 
listed in ppEnum is based on the order they match pszOptAttribs. 

ppEnum 

[out] The enumerated list of tokens found. 
Return values 

Value 

S_OK 

SPERR^UNINITIALIZED 
E_POINTER 
FAILED(hr) 

Example 

The following code snippet demonstrates getting a complete enumerated token list. Since no 
specific requirement is given (pszReqAttribs and pszOptAttribs are NULL), all values are 
returned for SPCAT_VOICES. 

HRESULT hr; 

CComPtr cpSpCategory; 
CComPtr cpSpEnumTokens ; 

hr = SpGetCategoryFromId(SPCAT_VOICES, SccpSpCategory) ; 
//Check return code 

hr ^ cpSpCategory- >EnumTokens (NULL, NULL, &cpSpEnumTokens) ; 
//Check return code 

© 1995j2_00p Microspft Corporation AlU^^ 
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ISpObjectTokeiiCategory::SetDefaultTokeiiI 



Description 

Function completed successfully. 

Data key interface is not initialized. 

At least one of the parameters is invalid or bad. 

Appropriate error message. 
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ISpObjectTokenCategory::SetDefaultTokenI 



ISpObjectTokenCategory::SetDefaultTokenId sets a specific Tokenid as the default for the 
category. 

The defaults are stored either directly in the category by setting the DefaultTokenID value in 
the category data key, or indirectly by the DefaultTokenlDLocation. 

HRESULT SetDefaultTokenId{ 
const WCHAR *pszTokenId 

); 

Parameters 

pszTokenId 

[in] The null-terminated string name of the Tokenid to be used as the default. 
Return values 

Value Description 

S OK Fxmction completed successfully. 

SPERR__UNINITIALIZED Data key interface is not initialized. 

E_INV ALID ARG pszTokenId is invalid or bad. 

FAILED(hr) Appropriate error message. 



ISpObjectTokenCategory::GetDefaultTokeii 



ISpObjectTokenCategoryrrGetDefaultTokenld retrieves the default Tokenid for the 
category. 



HRESULT GetDefaultTokenId( 
const WCHAR pszTokenId 

) ; 

Parameters 

pszTokenId 

[in] The null-terminated string name of the Tokenid used as the defauh. 



© 1995-2pO0JP4icrpspft Corporation^Allrigh^ reserved. 
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Return values 

Value 

S_OK 

SPERR_UNINITIALIZED 

E_POINTER 

FAILED(hr) 



Microsoft Speech SDK 
with SAPI 5.0 



Description 

Function completed successfully. 
Data key interface is not initialized. 
pszTokenId is invalid or bad. 
Appropriate error message. 



© 1 995-2000 Microsoft Con3oration All rights reserved 
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ISpObjectToken 

ISpObjectToken inherits from ISpDataKey. 
Methods in Vtable Order 



ISpObjectToken Methods 

SetlD 

GetiP 

GetCategory 

Createlnstance 

GetStorageFUeNa^^ 

RemoveStorageFileNa^^^^ 

Remove 

IsUISupported 

DisplayUI 



Description 

Sets the category ID for object token. 
Retrieves the object identifier for an object token. 
Retrieves the category if one is available for the 
specified token. 

Creates an instance of an object. 

Retrieves the object token file name from the registry. 

Removes the object token file name from the registry. 

Removes an object token. 

Determines if the UI associated with the object is 

supported. 

Displays the UI associated with the object. 

© 1995-2000 Microsoft Corporation All rights reserved 
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ISpObjectToken::SetId 

ISpObjectToken: rSetId sets the Categoryld for object token. 
This may be called only once. 
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HRESULT Setld( 

const WCHAR *pszCategoryId, 

const WCHAR *pszTokenIdf 

BOOL f Crea t elf No tExi s t 

); 



Parameters 



pszCategoryld 

[in] The null-terminated string name of category to set. 
pszTokenId 

[in] The mill-terminated string name of token to set. 
fCreatelfNotExist , . 

[in] A Boolean indicating the object is to be created if not currently existmg. 
allows the creation; FALSE does not. 

Return values 

Value Description 

S OK Function completed successfully. 

SPERR_ALREADY_INITIALIZED Category interface is already initialized. 
SPERR_TOKEN_DELETED Key has been deleted. 



Notes 

Categorylds appear in the fully quaUfied form as: 

"HKEY_LOCAL_MACHINE\SOFTWARE\Microsofl\Windows\CurrentVersion\ 
Speech\Recognizers" 

The only acceptable HKEYs are: 

HKEY_CLASSES_ROOT, 

HKEY_CURRENT_USER, 

HKEY_LOCAL_MACHINE, 

HKEY_CURRENT_CONFIG 



E INVALID ARG 



Either pszCategoryld and/or pszTokenId is invalid or 
bad. 



FAILED(hr) 



Appropriate error message. 
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ISpObjectToken: :GetID 



ISpObjectToken::GetID retrieves the object identifier for an object token. This ID can be 
used later to recreate a token instances. 

HRESULT GetID{ 

WCHAR * *ppszCoMemTokenId 

); 

Parameters 

ppszCoMemTokenId 

Address of a pointer to a null-terminated string that receives the identifier for the token 
object. The caller must call CoTaskMemFreeQ to free the string pomter. 

Return values 

Value Description 

S OK Function completed successfully. 

E POINTER ppszCoMemTokenId is invalid or bad. 

E_OUTOFMEMORY Exceeded available memory, 

SPERR_UNINITIALIZED Tokenid interface is not initialized. 

FAILED(hr) Appropriate error message. 



ISpObjectToken::GetCategory retrieves the category for a specified token if one is available. 



HRESULT GetCategory( 

ISpObj ectTokenCategory *-^ppTokenCategory 

); 

Parameters 

ppTokenCategory 

[out] The category interface for the token. ppTokenCategory must be freed when no 
longer required. 



© ]99_5-2000 Microsoft Cpippratjon, All rights reserved 
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ISpOb j ectToken : : GetCategory 
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Return values 

Value Description 

S OK Function completed successfully. 

E POINTER ppTokenCategory is invalid or bad. 

SPERR_UNINITIALIZED Token does not have a category. 

FAILED(hr) Appropriate error message. 

©J„915-2000 Microsoft Cprpgration AH rights. reserved. 



[This is preliminar}^ documentation and subject to change.] 

ISpObjectToken: :CreateInstance 

ISpObjectToken::CreateInstance creates an instance of an object. 



HRESULT Createlnstance ( 

lUnknown *pUnkOuter, 
DWORD dwClsContext, 
REPIID riid, 
void **ppvObject 

)} 

Parameters 

pUnkOuter 

[in] If the object is being created as part of an aggregate, this is a pointer to the 
controlling lUnknown interface of the aggregate. Otherwise, pUnkOuter must be NULL. 

dwClsContext , , _ .„ u u 

[in] Context in which the code that manages the newly created object will run. It should 
be one of the following values: 

CLSCTX_INPROC_SERVER 

CLSCTX_INPROC_HANDLER 

CLSCTX_LOCAL_SERVER 

CLSCTX_REMOTE_SERVER 

riid . . . . . 

[in] Reference to the identifier of the interface used to communicate with the newly 
created object. If pUnkOuter is NULL, this parameter is frequently the IID of the 
initializing interface; if pUnkOuter is non-NULL, riid must be IIDJUnknown. 

ppvObj'ect , . - . , J 

[out, iid_is(riid)] Address of pointer variable that receives the interface pomter requested 
in riid. Upon successful return, ppvObject contains the requested interface pointer. If the 
object does not support the interface specified in riid, the implementation must set 
ppvObject to NULL. 

Return values 

Value Description 

S OK Function completed successfully. 
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E_POINTER 

EJNVALIDARG 

SPERR_UNINITIALIZED 

SPERR_TOKEN„DELETED 
FAILED(hr) 



ppvObject is invalid or bad. 

pUnkOuter is invalid or bad. 

Either the data key or the token delegator interface is 
not initialized. 

Key has been deleted. 

Appropriate error message. 



Return values 

The following code snippet creates an InProc server instance. 



HRESULT hr; 

CComPtr cpSpObjectToken; 
CComPtr cpSpObjectWithToken; 

hr = SpGetDefaultTokenFromCategoryId(SPCAT__VOICES, SccpSpObjectToken) ; 
//Check return value 

hr = cpSpObjectToken->CreateInstance ( 

NULL, CLSCTX_INPROC_SERVER, IID_ISpObjectWithToken, 
{void **) &cpSpObjectWithToken 

) ; 

//Check return value 

© 1995-2000 Microsoft Cprporatjoa All rights resented 



[This is preliminai}^ dociimentation and subject to change.] 4^ 

ISpObj ectToken : : GetStorageFileName 

ISpObjectToken::GetStorageFiIeName retrieves the object token file name from the registry. 



HRESULT GetStorageFileName ( 
REFCLSID clsidCaller f 

const WCHAR ^pszValneName , 
int nFolder, 
WCHAR **ppszFilePath 

); 

Parameters 

clsidCaller 

[in] Globally unique identifier (GUID) of the calling object. 

pS2 VolllC J^QJHC 

[in] Address of a null-terminated string containing the registry key name. 
nFolder 

[in] Value specifying the folder from which to retrieve the location. 
ppszFilePath 

[out] Address of a pointer to the null-terminated string that receives the file path 
infonnation. Must be freed when no longer required. 
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Return values 

Value Description 

S OK Function completed successfully. 

E POINTER /Tp^zF/VePa^/? is invalid or bad. 

E OUTOFMEMORY Exceeded available memory. 

S_F ALSE A new file was created. 

E_IN VALID ARG psz ValueName is invalid or bad. 

SPERR_UNINITIALIZED Either the data key or the token delegate interface is 

uninitialized. 

SPERR_TOKEN_DELETED Key has been deleted. 

FAILED(hr) Appropriate error message. 

Example 

The following code snippet creates and removes a token object for a test file. 

HRESULT hr; 
GUID guidO; 

CComPtr cpSpObjectToken; 
CSpCoTaskMemPtr cpFileName; 

hr = SpGetDefaultTokenFromCategoryId(SPCAT__VOICES, &cpSpObjectToken) ; 
//Check return value 

Zeros t ruct (guidO) ; 

hr = cpSpObjectToken- >GetStorageFileName( 

guidO, L"TestFile", CSIDL_FLAG_CREATE, &cpFileName 

) ; 

//Check return value 



hr = cpSpObjectToken->Remove (&guidO) ; 
//Check return value 



) 1995-2000 Microsoft Corporation All rights reserved 
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ISpObjectToken::RemoveStorageFileName 

ISpObjectToken::RemoveStorageFileName removes the object token file name from the 
registry. 



HRESULT RemoveStorageFileName ( 
REFCLS ID cl si dCall er , 

const WCHAR -^pszyalueName, 
BOOL fDeleteFile 



Parameters 
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clsidCallcr 

[in] Globally unique identifier (GUID) of the calling object. 

psz Value Nutnc 

[in] Address of a null-terminated string containing the registry key name. 
fDeleteFile 

[in] Value specifying if the file should be deleted. TRUE deletes the file afterwards; 
FALSE does not. 

Return values 

Value Description 

S OK Function completed successfully, 

E INVALID ARG pszValueName is invalid or bad. 

SPERR_UNINITIALIZED Either the data key or token delegate interface is not 

initiaUzed. 

SPERR_TOKEN_DELETED Key has been deleted. 

FAILED(hr) Appropriate error message. 

Example 

The following code snippet creates a test file, removes it and manually deletes it. It may also 
have been deleted automatically by s^ning fDeleteFile to TRUE. 

HRESULT hr; 
GUID guidO; 

CComPt r cpSpOb j ec tToken ; 
CComPtr cpSpObjectWithToken; 
CSpCoTaskMemPtr cpFileName ; 

hr = SpGetDefaultTokenFromCategoryId(SPCAT_VOICES, &cpSpObj ect Token ) ; 
//Check return value 

Zeros truct (guidO) ; 

// Create subkeys and value item to be deleted 
hr = cpSpObjectToken->GetStorageFileName ( 

guidO, L"test file", CSIDL_FLAG_CREATE, &cpFileName 

) ; 

if (SUCCEEDED (hr) ) 

^ hr = cpSpObjectToken->RemoveStorageFileName(guidO, L"test fil 

//Check return value 

cpFileName . Clear ( ) ; 

} 

© 1995:2000 Microsoft Corporation „AU rights re_ser\^ed 



[This is prelimiamy documentation and subject to change.] -iS 

ISpObjectToken: rRemove 



file://C:\WIND0WS\TEMP\~hh2B lB.htm 



12/28/00 



Application-Level Interfaces 



Page 102 of 199 



ISpObjectTokenrrRemove removes a token object. 



HRESULT Remove ( 

const QUID *pclsidCaller 

); 

Parameters 

pclsidCaller 

[in] Address of the identifier associated with the object token to remove. If pclsidCaller 
is NULL, then the entire token is removed; otherwise, only the specified section is 
removed. 

Return values 

Value Description 

S OK Function completed successfully. 

E POINTER ;?c/5zY/Ca//er is invalid or bad. 

SPERR_UNINITIALIZED The token ID interface is uninitialized. 

SPERR_TOKEN_DELETED Key has been deleted. 

FAILED(hr) Appropriate error message. 

Example 

The following code snippet creates and removes a token object for a test file. 

HRESULT hr; 
GUID guidO; 

CComPtr cpSpObjectToken; 
CSpCoTaskMemPtr cpFileName; 

hr = SpGetDefaultTokenFromCategoryId(SPCAT_VOICES, &cpSpObjectToken) ; 
//Check return value 

ZeroStruct (guidO) ; 

hr = cpSpObjectToken->GetStorageFileName ( 

guidO, L"TestFile", CSIDL_FLAG_CREATE, &cpFileName 

) ; 

//Check return value 



hr = cpSpObjectToken->Remove (SguidO) ; 
//Check return value 



© 1995-2000 Microsoft Corporation AU rights resented 
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[This is preliminary documentation and subject to change.] 

ISpObjectToken:;IsUISupported 

ISpObjectToken::IsUISupported determines if the user interface (UI) associated with the 
object is supported. 

[local] HRESULT IsUISupported { 
REFGUID guidTypeOfUI, 
void ^pvExtraData, 
ULONG cbExtraData, 
lUnknown ^punkObj ec t , 
BOOL *pf Supported 

); 

Parameters 

guidTypeOfUI 

[in] Globally unique identifier (GUID) of the object mterface. 
pvExtraData 

[in] Pointer to additional information needed for the object. 
cbExtraData 

[in] Size, in bytes, of the ExtraData 
punkObject 

[in] Address of the lUnknown interface pointer. 

pfSupported ^ . ^, . ^ ^ - ^ ^ 

[out] Address of a variable that receives the value mdicatmg support for the mtertace. 
This value is set to TRUE when this interface is supported, and FALSE when it is not. 

Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG One of the parameters is invalid or bad. 

SPERR_UNINITIALIZED Either the data key or token delegate interface is not 

~ initialized. 

SPERR_TOKEN_DELETED Key has been deleted. 

FAILED(hr) Appropriate error message. 

© ;995-20p0 Microsoft Cprppratioii„ All rlghte reserved. 
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ISpObjectToken: :DisplayUI 

ISpObjectToken::DisplayUI displays the user interface (UI) associated with the object. 



Is 
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[local] HRESULT DisplayUI { 

HWND hwndParen t , 

const WCHAR *pszTitle, 

REFGUID guidTypeOfUI , 

void *pvExtraData, 

ULONG cbExtraDa ta , 

lUnknown *punkObj act 

) ; 

Parameters 



hwndParent 

[in] Specifies the handle of the parent window. 
pszTitle 

[in] Address of a null-terminated string containing the window 
guidTypeOfUI 

[in] Globally unique identifier (GUID) of the object. 
pvExtraData 

[in] Pointer to additional information needed for the object 
cbExtraData 

[in] Size, in bytes, of the ExtraData 
punkObject 

[in] Address of the lUnknown interface pointer. 

Return values 

Value 

S_OK 

E_INVALIDARG 
SPERR_UNINITIALIZED 

SPERR_TOKEN_DELETED 
FAILED(hr) 



Microsoft Speech SDK 
with SAP! 5.0 



[This is preliminary documentation and subject to change.] 

lEnumSpObj ectTokens 

The lEnumSpObiectTokens interface is used to enumerate speech object tokens. 
When to Implement 

Implement this interface when a caller wants to be able to enumerate the speech token 
identifiers contained in a speech object. 



Description 

Fimction completed successfully. 

One of the parameters is invalid or bad. 

Either the data key or token delegate interface is not 
initialized. 

Key has been deleted. 
Appropriate error message. 



© 1 995-2000 Microsoft Corporation rights reserved. 
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When to Use 

Call methods of the lEnumSpObjectTokens interface to enumerate the speech object tokens. 
Methods in Vtable Order 



lEnumSpObjectTokens Methods 

Next 

Skip 

Reset 
Clone 

GetCount 



Description 

Retrieves the next object token in the enumeration 
sequence. 

Skips a specified number of object tokens in the 
enumeration sequence. 

Resets the enumeration sequence to the beginning. 

Creates a new enumerator object vdth the same items. 

Locates a specific token in the enumeration. 

Retrieves the number of object tokens contained in the 
enumeration sequence. 



©. 19_?5-_200_0 Microsoft Corporation^ AU rights reserv'ed 



[This is preliminat}^ documentation and subject to change.] 

lEnumSpObjectTokens: :Next 

lEnumSpObjectTokens: :Next retrieves the next object token in the enumeration sequence. 

If there are fewer than the requested nimiber of elements left in the sequence, the remaining 
elements are retrieved. 

HRESULT Next( 

ULONG celt, 
ISpOb j ectToken * *pel t , 
ULONG *pceltFetched 

); 

Parameters 

celt 

[in] The number of object tokens to retrieve. 

pelt , . 

[out] Address of an array that receives ISpObjectToken pomters. If an error value is 

returned, no entries in the array are valid. 

vccltFctchcd 

[out] Address of a variable that receives the number of ISpObjectToken pointers actually 
copied to the array. This parameter cannot be NULL if celt is greater than one. If this 
parameter is NULL, celt must be one. 

Return values 

Value Description 

S OK Function completed successfully. 
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E_POINTER 

E INVALIDARG 



SPERR^UNINITIALIZED 
FAILED (hr) 



pelt is bad or invalid. 

pceltFetched is bad or invalid or the number of objects 
is invalid. 

Attribute parser interface is not initialized. 
Appropriate error message. 
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lEnumSpObjectTokens: rSkip 



IEiiumSpObjectTokens::Skip skips a specified number of object tokens in the enumeration 
sequence. 

HRESULT Skip{ 
ULONG celt 

); 

Parameters 

celt 

[in] Nximber of object tokens to skip in the enumeration sequence. 
Return values 

Value Description 

S OK Number of elements skipped was ce/r 

S F ALSE Number of elements skipped was less than celt 

SPERR^UNINITIALIZED Attribute parser interface is not initialized. 

FAILED (hr) Appropriate error message. 



IEnumSpObjectTokens::Reset resets the enumeration sequence to the beginning. 

HRESULT Reset ( void ) ; 

Parameters 

None 

Return values 



©1995-2000 MjcrpAoft Corporation. AILrights reserved. 
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lEnumSpObjectTokens: :Reset 
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Return values 



Value 

S_OK 

SPERR UNINITIALIZED 



Description 

Method completed successfully. 
Attribute parser interface is not initialized. 



© 1995-2000 Microsoft Corpqration_All rights i^^^^ 
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lEnumSpObjectTokens: : Clone 



IEnumSpObjectTokens::Clone creates a new enumerator object with the same items. 

Returns a new enumerator object with the same items but an independent index. The items in 
the clone are not guaranteed to be in the same order as the original enumerator. 

HRESULT Clone ( 

lEnumSpObj ectTokens **ppEnum 

) ; 

Parameters 



[out] Address of the lEnumSpObj ectTokens pointer variable that receives the interface 
pointer to the cloned enumerator. Using Clone, it is possible to record a particular pomt 
in the enumeration sequence and then return to that point at a later time. The enumerator 
returned is of the same interface type as the one being cloned. 

Return values 

Value Description 

S OK Function completed successfully. 

SPERR^UNINITI ALIZED Attribute parser interface is not initialized. 

FAILED (hr) Appropriate error message. 



© _1 995-2000 MicrosoACorporation^ A!l rights reserved 
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lEnumSpObjectTokens: -.Item 



IEnumSpObjectTokens::Item locates a specific token in the enumeration. 



HRESULT I tern { 

ULONG Index f 

ISpObjectToken **ppToken 

) ; 
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); 

Parameters 

Index 



[in] Value indicating which token in the enumeration sequence to locate. 
ppToken 

[out] Address of an ISpObjectToken interface pointer. 



Return values 

Value 

S_OK 

SPERR_NO_MOREJTEMS 
E_POINTER 

SPERR_UNINITIALIZED 
FAILED (hr) 



Description 

Function completed successfully. 

Index is greater than the amount of items available. 

ppToken is bad or invalid. 

Attribute parser interface is not initiaUzed, 

Appropriate error message. 

© 1 995:2000 Microsoft Corporatipn AU rightsxesen'ed. 



[This is preliminary documentation and subject to change,] 

lEnumSpObjectTokens: :GetCount 

IEnumSpObjectTokens::GetCount retrieves the number of object tokens contained in the 
enumeration sequence. 



HRESULT GetCount{ 
ULONG -i^pulCount 

) ; 

Parameters 



pulCount 

[out] The number of object token items contained in the enumeration sequence. 



Return values 

Value 

S_OK 

E_POINTER 

SPERR_UNINITIALIZED 
FAILED (hr) 



Description 

Function completed successfully. 
pulCount is bad or invalid. 
Attribute parser interface is not initialized. 
Appropriate error message. 



© 1995-2000 MicxQsoft Conwmtion.„AlJ_ngh reserved. 
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Microsoft Speech SDK 
with S API 5.0 




[This is preliminary documentation and subject to change.] 



ISpObjectWithToken 



Methods in Vtable Order 



ISpObjectWithToken Methods 

SetpMectTpken 

GetObjectTpken 



Description 

Creates an object token. 
Retrieves an object token. 
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ISpObjectWithToken::SetObjectToken 



ISpObjectWithToken::SetObjectToken creates an object token. 

HRESULT Se tOb j ec tToken ( 

ISpObj ectToken *pToken 

); 

Parameters 

pToken . 1.1. 1 

[in] Address of the ISpObj ectToken interface creating this object token. 

Return values 

Value Description 

S OK Function completed successfully. 

E POINTER /^rofew is invalid or bad. 

E_OUTOFMEMORY Exceeded available memory. 

FAILED(hr) Appropriate error message. 



ISpObj ectWithToken : : GetObj ectToken 



© 1995:2p(»_Microsofl Coiporation. All rights reserved. 



[This is preliminary documentation and subject to change.] 
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ISpObjectWithToken::GetObjectToken retrieves an object token. 



HRESULT Ge tOb j ectToken { 

ISpOb j ectToken * *ppToken 

); 

Parameters 

ppToken . 11. i 

[out] Address of an ISpObj ectToken interface that receives the object token. 

Return values 

Value Description 

S OK Function completed successfully. 

E POINTER ^^rofen is invalid or bad. 

E_OUTOFMEMORY Exceeded available memory. 

FAILED(hr) Appropriate error message. 

© 1995-2000 MicrospftCorporatipn. AJJji^hts reserved 



Microsoft Speech SDK 

with SAPI 5.0 

[This is preliminary documentation and subject to change.] 

ISpResourceManager 

The ISpResourceManager interface provides access to the shared resources between different 
speech applications. 

When to Use 

Call methods of the ISpResourceManager interface to access the functionality of the shared 
resources. 

Note: This interface inherits from IServiceProvider. 
Methods in Vtable Order 
ISpResourceManager Methods Description 

SetObject Adds a service object to the current service list. 

GetObject Retrieves a service object from the current service list. 

© 1995:2000 Microsoft Corporation _AiLnghts„ resented 

[This is preliminary documentation and subject to change.] 
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[This is prelimiimr)^" documentation and subject to change.] ^» 

ISpResourceManager : rSetObject 

ISpResourceManager::SetObject adds a service object to the current service list. 

HRESULT SetObject( 

REFGUID gui dServl celd , 

lUnknown *pUnkObj ec t 

); 

Parameters 

guidServiceld 

[in] The unique identifier of the service. 
pUnkObject . 

[in] Address of the lUnknown interface of the object that is setting the service. 

Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG pUnkObject is bad or invalid. 

E OUTOFMEMORY Exceeded available memory. 

FAILED(hr) Appropriate error message. 

© i 995-2000 _Mic_rpsoftCorporati A]] rightejeserved 

[This is prelimim«*y docimientation and subject to change.] 4^ 

ISpResourceManager : :GetObject 

ISpResourceManager::GetObject retrieves a service object from the current service list. 
If the HRESULT is not S_OK, then the caller must delete this object manually. 



HRESULT GetObject( 

REFGUID gu i dServi celd, 
REFCLSID ObjectCLSID, 
REFIID OhjectllD, 
BOOL f Re leas eWhenNoRef s , 
void **ppObject 

); 

Parameters 
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guidServiceld 

[in] The unique identifier of the service. 
ObjectCLSID 

[in] Class identifier of the object. 
ObjectllD 

[in] Interface identifier of the object. 

fReleaseWhenNoRefs r/^rr^T^TTT- u u- + • 

[in] Boolean indicating whether or not the object is an aggregate. It 1 RUb, the object is 
not a aggregate and may be released when no longer needed. FALSE indicates that the 
object is an aggregate and must be manually freed when no longer required. 

ppObject 

[out] Address of a pointer that receives the interface pointer of the service. 
Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG One or more arguments are invalid. 

E POINTER j7p06/ec? is bad or invalid. 

REGDB_E_CLASSNOTREG Class is not registered. 
E OUTOFMEMORY Exceeded available memory. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Cpjporation.AlLrigbts reserved. 



Microsoft Speech SDK 
with SAPI 5.0 



[This is preliminarj^ documentation and subject to change.] 

ISpTask 

The ISpTask interface allows a single thread to process several events. This permits smaller 
tasks to run without interfering of more important processes. After the task object is notified, 
ISpTask: :Execute may be called to implement the effects. 

When to Use 

ISpTask is most useful with multiprocessor computers. Its allows an efficient allocation of 
tasks based on the current availability of processor time. 

Note: 

This is not a COM interface. 
Methods in Viable Order 

ISpTask Methods Description 
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Implements the processing of a thread. 

©1 995-2000 Microsoft Corporation All rights reserved 



[This is preliminar}'^ documentation and subject to change.] ^ 

ISpTask: -.Execute 

ISpTask::Execute implements the processing of a thread. This will be application specific. 



virtual HRESULT STDMETHODCALLTYPE Execute ( 

void *pvTaskDatar 

volatile const BOOL *pfContinueProcessing 
) = 0; 

Parameters 

pvTaskData 

[in] The specific information for the application. 
pfContinueProcessing . 

[in] Boolean indicating if the process should continue. TRUE continues the process; 

otherwise FALSE. 
Return values 

The return value is application specific. 

©i99_5-2000 Microsoft Cpiporation. Ajl rights reserved. 

Microsoft Speech SDK 



with SAPI 5.0 - ^ 

[This is preliminary^ documentation and subject to change.] 

Speech Recognition Interfaces 

The following section covers: 

• ISpRecoContext 

• ISpRecoGrammar 

• ISpRecoResult 

• ISpRecoRnizer 

• ISpPhrase 

• ISpPhrase Alt 

• ISpProperties 

© 1995-2000 Microsoft Corporation All rights reserved . 

Microsoft Speech SDK 
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with SAPI 5.0 



[This is preliminary documentation and subject to change. 

ISpRecoContext 

This interface inherits from ISpEyentSorace. 
Methods in Vtable Order 



ISpRecoContext Methods 

GetRecognker 

CreateGrammar 

GetStatus 

GctMaxAIternates 

SetMaxAlterna^^ 

SetAudioOptions 

GetAudioOjtion 

DeserializeResult 

Bookmark 

SetAdaptationPata 

Pause 

Resume 

SetVoice 
GetVoice 

SetYoicePurgeEyent 
GetVoicePurgeEvent 



Description 

Returns a reference to the current engine object. 

Creates a SpGrammar object. 

Retrieves current context state information. 

Retrieves the maximum number of ahemates that will 
be generated for command and control grammars. 

Sets the maximum number of alternates returned for 
command and control grammars. 
Sets the audio options for results from this context. 
Retrieves the audio options for the context. 
Creates a new result object from a serialized result. 
Sets a bookmark within the current recognition stream. 

Passes a block of text to the SR engine which it can 

use to adapt the active language models. 

Pauses the engine object to synchronize with the SR 

engine. 

Resumes the SR engine from the paused state and 
restarts the recognition process. 

Sets the associated ISpVoice to this context. 
Retrieves a reference to the associated ISpVoice 
object. 

Sets the SR engine events that stop audio output, and 
purges the current speaking queue. 
Retrieves the set of SR engine events that stop audio 
output, and purges the current speaking queue. 

© l_995-2O0O Microsoft Corporation AlUlg^^ resented 



[This is preliminaiy documentation and subject to change.] 

ISpRecoContext: iGetRecognizer 

ISpRecoContext: :GetRecognizer returns a reference to the current recognition instance object 
associated with this context. 
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HRESULT GetRecognizer ( 

ISpRecognizer **ppRecognizer 

); 

Parameters 

ppRecoInstance 

[out] Address of a pointer that receives the ppRecognizer interface. 
Return values 

Value Description 

S OK Function completed successfully. 

E_POINTER Invalid pointer. 

FAILED (hr) Appropriate error message. 



© 1995-_200p Microsoft Corporation AH rights reserved 



[This is preliminary documentation and subject to change.] 

ISpRecoContext: rCreateGrammar 

ISpRecoContext::CreateGrammar creates a SpRecoGrammar object. 

HRESULT CreateGrainmar ( 

DWORD PTR ^pdwpGraxcmarldf 
ISpRecoGranimar * *ppGranmar 

) ; 

Parameters 

^^^^%n]Sp7M^ the grammar identifier. This identifier is associated with all result objects 

from the grammar. The identifier is used by the application and is not required. 
ppGrammar 

[out] Address of a pointer which receives the I SpRecoGrammar object 
Return values 

Value Description 

S OK Function completed successfully. 

E POINTER ppGrammar is invalid. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation. All rights reserved 

[This is preliminary documentation and subject to change.] ^»"» 
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[Tills is preliminary documentation and subject to change.] ^ 

ISpRecoContext: :GetStatus 

ISpRecoContext::GetStatus retrieves current state information associated with a context. 

HRESULT GetStatus{ 

SPRECOCONTEXTSTATUS *pStatus 

); 

Parameters 

pStatus , . .1 ^ ^ 

[out] Address of the SPRECOCONTEXTSTATUS structure that receives the context 

state information. 
Return values 

Value Description 

S OK Function completed successfully. 

E POINTER ^Sft/fM^ is invalid or bad. 

FAILED (hr) Appropriate error message. 

© 1995:2000 MicrpAoftCorpOT^^ „Ali rights reserved 



[This is preliminar}^ documentation and subject to change.] 

ISpRecoContext: : GetMax Alternates 

ISpRecoContext: :GetMaxAltemates retrieves the maximum number of altemates that the SR 
engine will return for command and control granmiars associated with this context. Note that 
this method has no effect on dictation grammars, 

HRESULT GetMaxAlternates ( 
ULONG *pcMaxAl t erna tes 

); 

Parameters 

pcMaxA Iternates 

[out] The maximum number of altemates. 

Return values 
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Value 

S_OK 

E_POINTER 
FAILED(hr) 



Description 

Function completed successfully. 
pcMaxAlternates is invalid or bad. 
Appropriate error message. 



©1995:2000 Microsoft CgrporMon_AU m^ts reserved 



[This is preliminary documentation and subject to change,] 



4- ^ 



ISpRecoContext: :SetMaxAlternates 



ISpRecoCoiitext::SetMaxAlternates sets the maximum number of alternates the SR engine 
returns for command and control grammars associated with this recognition context. Note that 
this method has no effect on dictation grammars. 

HRESULT SetMaxAlternates ( 
DWORD cMaxAlternates 

); 

Parameters 

[in] Specifies the maximum number of alternates the engme will return. 
Return values 

Value Description 

S OK Function completed successfully. 



ISpRecoContext: tSetAudioOptions sets the audio options for result objects from this 
recognition context. 

The SetAudioOptions method enables or disables the retention of audio with result objects and 
can change the retained audio format. By default, when an audio format is not specified, the 
audio will be retained in the same format as the SR engine used to perform the recognition. 

HRESULT SetAudioOptions ( 

SPAI3DI00PTI0NS Options, 

const GUID -^pAudioFormatld, 

const WAVEFORMATEX * pVfaveFormatEx 

); 



Parameters 



© 1995-2000 Microsoft Corporation MX rights reserved 



[This is preliminary documentation and subject to change,] 




ISpRecoContext: : SetAudioOptions 
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Parameters 

Options ^ . ^ , „ . 

[in] Flag of type SPAUDIOOPTIONS indicating the option. It must be one of the 

following: 

Value 

SPAO_NONE Do not retain 

audio for 
results. 

SPAO_RETAIN_AUDI0 Retain audio 

for all future 
results. 

pAudioFormatId . ^^^.^ tx' 

[in] The audio stream format GUID. Usually this value is SPFIDJFaveForamatEx. If 
this value is NULL, the retained audio format will not be changed. 

pWaveFormatEx . .^^ ^ 7 r-. u 

[in] The audio stream wave format. This is only valid if ^pAudioFormatld — 
SPFIDJVaveFormatEx. 

Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG Options is not one of the correct types. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation AH rights reserved 



n^his is preliminary^ documentation and subject to change.] 

ISpRecoContext: rGetAudioOptions 

ISpRecoContext::GetAudioOptions retrieves the audio options for a given stream. 



HRESULT GetAudioOptions ( 

SPAUDIOOPTIONS * Options, 

cons t GUI D ^pAudi oForma t Id , 

const WAVEFORMATEX **pWaveFormatEx 

); 

Parameters 

Options ^ . ^ ^1 * , , 

[out] Flag of type SPAUDIOOPTIONS indicatmg the options set for this context. 

pAudioFormatId 

[in] The audio stream GUID to retrieve. This value can be NULL. 
p WaveFormatEx 
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[in] The audio stream wave format to retrieve. This can be NULL \i pAudioFormatId is 
NULL. 

Note: This data must be freed using r.CoTaskMemFreeQ. 
Return values 

Value Description 

S OK Function completed successfully. 

E POINTER One of the pointers is invalid or bad. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation All rights reserved 

[This is preliminary documentation and subject to change,] <SJ 

ISpRecoContext: -.DeserializeResult 

ISpRecoContext::DeserializeResult creates a new result object from a serialized result. 

HRESULT DeserializeResult { 

const SPSERIALIZEDRESULT pSerializedResnlt , 
ISpRecoResult **ppResult 

); 

Parameters 

pSerializedResult 

[in] The current serialized result. 
ppResult 

[out] The unserialized result object. 

Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG pSerializedResult is invalid or bad. 

E POINTER j!7pife5w// is invalid or bad. 

E^OUTOFMEMORY Exceeded available memory. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation All rights reserved 

[This IS preliminary^ documentation and subject to change.] ^0 

ISpRecoContext: rBookmark 
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ISpRecoContext: rBookmark 

ISpRecoContexttiBookmark sets a bookmark within the current recognition stream. When 
the engine reaches the specified stream position, a bookmark event is added to the event queue. 

HRESULT Bookmark ( 

SPBOOKMARKOPTIONS Options, 
ULON6LONG ullStreamPosition, 
LP ARAM IParamEvent 

); 

Parameters 

Options_^ Flags of type SPBOOKMARKOPTIONS indicatmg the options associated with the 
bookmark. Must be one of the following values: 

SPBOJSfONE Context will not be paused when a bookmark event occurs. 

SPBO_PAUSE Context is paused when a bookmark event occurs. 

ullStreamPosition 

[in] The position of the bookmark within the stream. 

If SP STREAMPOS ASAP is specified, the bookmark event will occur when the engine 
reaches a synchronization point. This is usually combined with SPBO_PAUSEto 
asynchronously pause the recognition stream. If SP_STREAMPOS_REALTIME is 
specified, the bookmark event occurs when the SR engine reaches tiie point where the 
audio device is at the time of the call. 

IParamEvent , , , . .... 

[in] The Iparam for the SAPI bookmark event, and can be any value the application uses 

to uniquely identify this bookmark event. 
Return values 

Value Description 

S OK Fimction completed successfiiUy. 

E INVALIDARG Options has a bad value. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation All rights reserved 

[This is preliminar>' documentation and subject to change.] '9 

ISpRecoContext: : SetAdaptationData 

ISpRecoContext::SetAdaptationData sets a string to be adapted by the current recognition 
context. 

HRESULT SetAdaptationData ( 

const WCHAR *pAdaptationData , 
const ULONG cch 
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const ULONG cch 

); 

Parameters 

pAdaptationData 

[in] The string to adapt. 

cch 

[in] The nximber of characters in pAdaptationData. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG pAdaptationData is invalid or cch equals zero. 

E_OUTOFMEMORY Exceeded available memory. 

FAILED(hr) Appropriate error message. 



ISpRecoContext::Pause requests the engine object to pause and synchronize with the SR 
engine. 

The SR engine is paused at its synchronization point to allow grammars and rule states to be 
changed freely. The paused condition remains until the Resume method is called. 

Note: The caller must call Resume once for every call that is made to Pause. 

HRESULT Pause ( 

DWORD dwFlags 

); 

Parameters 

dwFlags 

[in] Reserved, must be 0. 

Return values 

Value Description 

S_OK Function completed successfully. 



• Pausing the SR engine will stop the recognition activity, but input audio will continue to 
be collected. 



© ! 995-2000 Microsoft Cprppratipn^ AlLri^hts_ reserved 
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ISpRecoContext: :Pause 



Note: 
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ISpRecoContext: '.Resume 



ISpRecoContext::Resume releases the SR engine from the paused state and restarts the 
recognition process. 

This method must be called after a call to ISpRecoContext: :Pa^^^ a bookmark event occurs 
that pauses the recognition engine, or an auto-pause rule is recognized. 

HRESULT Resume { 
DWORD dwRe served 

); 

Parameters 

dwReserved 

[in] Reserved, must be 0. 

Return values 

Value Description 

S_OK Function completed successfiiUy. 



ISpRecoContext: :SetVoice sets the associated ISpVoice to an object. 



HRESULT SetVoice( 

I.^&pA^^. *p^oi ce , 

BOOL fAl 1 owForma t Changes 

); 

Parameters 

pVoice 

[in] The voice interface to be associated. 
fAllowFormatChanges 

[in] Boolean allowing the voice format alteration by the engine. 

Return values 



© 1995:2000 Microsoft Corporation^ reserved. 
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ISpRecoContext: : Set Voice 
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Value Description 

S OK Fxmction completed successfully. 

E POINTER /?Fc?zce is invalid or bad. 

FAILED(hr) Appropriate error message. 



p 1995-2000 MicrosqftCorporation 



[This is preliminary documentation and subject to change.] 

ISpRecoContext: : Get Voice 

ISpRecoCoiitext::GetVoice retrieves a reference to the associated ISpVoice object. 

HRESULT GetVoice( 

I SpVqice * *ppVoi ce 

); 

Parameters 

ppVoice 

[in] Address of the ISpVoice interface. 
Return values 

Value Description 

S OK Function completed successfully, 

FAILED(hr) Appropriate error message. 

E_POINTER Invalid pointer. 

© 1995-2000 Micro soft Corporation. AH PS^^ts reserved. 



[This is preliminary docmtientation and subject to change.] 

ISpRecoContext: : SetVoicePurgeEvent 

ISpRecoContext::SetVoicePurgeEvent sets the SR engine events that stop audio output, and 
purges the current speaking queue. It passes the events as extra event interests to the engine. 



HRESULT SetVoicePurgeEvent ( 

ULONGLONG ullEventlnterest 

); 

Parameters 
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ullEventlnterest 



[in] The set of flags indicating the event interests. One of the following must be 



SPEI_REQUESTUI 

SPEI_INTERFERENCE 

SPEI_END_SR_STREAM 

SPEI_SR_BOOKMARK 

SPEI_SOUNDSTART 

SPEI_SOUNDEND 

SPEI_PHRASESTART 

SPEI_HYPOTHESIS 

SPEI_RECOGNITION 

SPEIFALSERECOGNITION 

Return values 

Value Description 

S OK Function completed successfully. 

E_INVALIDARG One or more of the interests set is not allowed. 

FAILED(hr) Appropriate error message. 



ISpRecoContext:: Get VoicePurgeE vent 



ISpRecoContextnGetVoicePurgeEvent retrieves the set of SR engine events that stop audio 
output, and purges the current speaking queue. The events are set by 
ISpRecoContext::SetVoiceP^^ 



HRESULT GetVoicePurgeEvent ( 

ULONGLONG * pnllE-ventIn t eras t 

); 

Parameters 

pullEventlnterest 

[out] The set of flags indicating the event interests. 

Return values 



included: 



© ] 995-2000 Microsoft Corporation. All rights reserved . 
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Value 

S_OK 

E_POINTER 
FAILED(hr) 



Microsoft Speech SDK 
with SAPI 5.0 



Description 

Function completed successfully. 
pullEventlnterest is invalid or bad. 
Appropriate error message. 



© 1995-2000 Microsoft CorppraUon^ All rights reserved 



[This is preliminar>' documentation and subject to change.] 

ISpRecoGrammar 

Methods in Vtable Order 



ISpRecoGrammar Methods 
GetGrammarld 

GetRecoContext 

LpadCmdFromFile 

LoadCmdFromObject 

LoadCmdFrqmResou 

LpadCmdFrom 

LoadCmdFTO 

SetRuleState 

SetRuIeldState 

LoadDictatipn 

UnloadDictatipn 

SetPictationState 

SetWordSequenceData 

SetTextSelec^^^^^^ 

IsPronoiinceable 
SetGrammarState 

SaveCmd 



Description 

Retrieves the grammar identifier associated with the 
application. 

Retrieves the context object that loaded this 
grammar. 

Loads a command from a file. 

Loads a command from an object. 

Loads a command from resource. 

Loads a command from memory. 

Loads a command from a proprietary grammar. 

Activates or deactivates a rule by its RuleName. 

Activates or deactivates a rule by its RulelD. 

Loads a dictation for an engine. 

Unloads a dictation from an engine. 

Sets a dictation state to active or inactive. 

Sets word sequence data used by <TEXTBUFFER>. 

Sets the insertion point (using word sequence data 
buffer). 

Determines if the word has a pronunciation. 

Changes the global granmiar state. 

Allows applications using dynamic grammars to 
save the current grammar state to a stream. 

© 1995-2000 Microsoft Corporation. All rights reserved 
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[Tliis is preliminan^ documentation and subject to change.] 



ISpRecoGrammar: :GetGrammarId 



ISpRecoGrammar::GetGrammarId retrieves the grammar identifier associated with the 
application. 

HRESULT GetGrammarld ( 

DWORD_PTR *pdwpGrammarId 

); 

Parameters 

pdwpGrammarld 

[out] Address of the grammar identifier associated with the grammar. 

Return values 

Value Description 

S_OK Fimction completed successfully. 

E_POINTER pdwGrammarld is invalid or bad. 



ISpRecoGrammar: :GetRecoContext retrieves the context object that loaded this grammar. 

HRESULT GetRecoContext ( 

ISpRecoContext **ppRecoCtxt 

); 

Parameters 

ppRecoCtxt 

[out] Address of a pointer to an ISpRecoContext object that receives the recognition 
context object pointer. 

Return values 

Value Description 

S_OK Function completed successfully. 



© 1995-2000 Microsoft Corporation. All rights reserved 
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ISpRecoGrammar: : GetRecoContext 
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E_POINTER ppRecoCtxt is invalid or bad. 

FAILED(hr) Rule not loaded. 

© J995-20pO U\crqsgftC^or]^m\m_A]\n 



[This is preliminary documentation and subject to change.] 

ISpRecoGrammar : :LoadCmdFromFile 

ISpRecoGrammar::LoadCmdFromFile loads a command from a file. If the file is an XML 
file, the information is compiled on-the-fly. Otherwise Options must be SPLO^DYNAMIC for 
it to compile. The file has to reside on the local machine (no URL loads). 

HRESULT LoadCmdFroinFile ( 

WCHAR *ps2Fi I eJ\rame, 

SPLOADOPTIONS Options 

); 

Parameters 

pszFileName 

[in, string] The file name containing the command. 
Options 

[in] Flag of type SPLOADOPTIONS indicating whether the file should be loaded 
statically or dynamically. 

Return values 

Value Description 

S_OK Fimction completed successfully. 

E_INVALIDARG pszFileName is invalid or bad. Alternatively, Options is 

neither SPLO_STATIC nor SPLO_DYNAMIC. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation, AW rights resented 



[This is preliminary documentation and subject to change*] 

ISpRecoGrammar::LoadCmdFromObject 

ISpRecoGrammar: :LoadCmdFromObject loads a command from an object. 



HRESULT LoadCmdFromOb j ect ( 
REFCLSID rcid, 
const WCHAR ^pszGrarmarName, 
SPLOAD OPTIONS Options 

); 
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Parameters 

rcid 

[in] The reference class ID of the object containing the command. 
pszGrammarName 

[in, string] The grammar name of the object containing the command. 
Options 

[in] Flag of type SPLOADOPTIONS indicating whether the file should be loaded 
statically or dynamically. 

Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG pszGrammarName is invalid or bad, Altematively, 

Options is neither SPLO_STATIC nor 
SPLO_DYNAMIC. 

FAILED(hr) Appropriate error message. 

© 1 995:2000 Microsoft Corporation. All rightsxesen^d 



[This is preliminary documentation and subject to change.] 

ISpRecoGrammar::LoadCmdFromResource 

ISpRecoGrammar::LoadCmdFromResource loads a command from resource. 

HRESUIjT LoadCmdFromRe source ( 
HMODULE hModule, 
const WCHAR *pszResourceName , 
const WCHAR *pszResourceType , 
WORD wLangu age , 

SPLOADOPTIONS Options 

); 

Parameters 

hModule 

[in] Handle to the module w^hose file name is being requested. If this parameter is NULL, 

it passes back the path for the file containing the current process. 
pszResourceName 

[in, string] The name of the resource. 
pszResourceType 

[in, string] The type of the resource. 
wLanguage 

[in] The language ID. 
Options 

[in] Flag of type SPLOADOPTIONS indicating whether the file should be loaded 
statically or dynamically. 
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Return values 



Value 

S_OK 

E INVALIDARG 



FAILED(hr) 



Description 

Function completed successfully. 

Either pszResourceName or pszResourceType is invalid 
or bad. It may also indicate hModule could not be 
found. Alternatively, Options is neither 
SPLO_STATIC nor SPLO_DYNAMIC. 

Appropriate error message. 



© 1995-2000 Microsoft Corpo^^ ns^ts reserved. 
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ISpRecoGrammar::LoadCmdFromMemory 

ISpRecoGrammarrrLoadCmdFromMemory loads a command ftom memory. 

HRESXJLT LoadCiadFroinMemory ( 

const SPBINARYGRAMMAR *pBinaryData , 
SPLOADOPTIONS " Options 

); 

Parameters 

pBinaryData 

[in] The serialized header buffer. 
Options 

[in] Flag of type SPLOADOPTIONS indicating whether the file should be loaded 
statically or dynamically. 

Return values 



Value 

S_OK 

E INVALIDARG 



FAILED(hr) 



Description 

Function completed successfully. 

Either pBinaryData or one of its members is invaUd or 
bad. It may also indicate pBinaryData->FormatId is 
not SPGDF_ContextFree. Alternatively, Options is 
neither SPLO„STATIC nor SPLO_DYNAMIC. 

Appropriate error message. 
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ISpRecoGrammar::LoadCmdFromProprieta 
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ISpRecoGrammarrrLoadCmdFromProprietaryGraminar loads a command from a 
proprietary grammar. 

HRESULT LoadCmdFromProprietaryGrammar ( 
REFGUID rgu x dParam , 

const WCHAR ^pszStringParamf 
const void *pVDataPa.ram, 
ULONG cbDa taSi ze , 

SPLOADOPTIONS Options 

); 

Parameters 

rguidParam 

[in] Unique identifier of the grammar. 
pszStringParam 

[in, string] The string command. 
pvDataParam 

[in] Additional information for the process. 
cbDataSize 

[in] The size, in bytes, oipvDataParam, 
Options 

[in] Flag of type SPLOADOPTIONS indicating whether the file should be loaded 
statically or dynamically. This value must be SPLO_STATIC. 

Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG pszStringParam or pvDataParam is invalid or bad. 

Alternatively, Options is not SPLO__STATIC. 

FAILED(hr) Appropriate error message. 

©_l995-200p Microsoft Corporation^^l] ri^hts_reseryecl, 

[This is preliminary docimentatioB and subject to change.] '^p 

ISpRecoGrammar: rSetRuleState 

ISpRecoGrammar::SetRuIeState activates or deactivates a rule by its RuleName. 

HRESULT SetRuleState( 

const WCHAR *pszlslame, 
const WCHAR *pszValue, 
SPRULESTATE NevjState 

); 

Parameters 

pszName 

[in, string] Address of a null-terminated string containing the rule name. If NULL, all 
rules are affected. 
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pszValue 



[in, string] Address of a null-terminated string containing the rule value. If NULL, all 
values are affected. 
NewState 

[in] Flag of type SPRULESTATE indicating the new rule state. 
Return values 

Value Description 

S_OK Function completed successfully. 

EINVALIDARG pszName or pszValue is invalid or bad. 

SPERR_UNINITIALIZED The object has not been properly initialized. 

FAILED(hr) Appropriate error message. 



The following snippet loads a grammar, then attempts to activate a single rule ("playcard") and 
immediately deactivate it. 

HRESULT hr; 

CCoinPtr<ISpRecognizer> cpRecognizer; 
CComPtr<ISpRecoContext> cpRecoContext ; 
CComPtr< ISpRecoGrammar> cpRecoGrammar ; 



hr = InitReco (cpRecognizer, CLSID_SpInprocRecogni2er, cpRecoContext); 
//Check return value 

hr = LoadGrammar (cpRecoContext, TESTGRAMMAR_FILENAME, cpRecoGrammar, GR 
//Check return value 

hr = cpRecoGrammar- >SetRuleState (L"playcard", NULL, SPRS_ACTIVE) ; 
//Check return value 



//Deactivate the rule 

hr = cpRecoGrammar->SetRuleState(L"playcard", NULL, SPRS_INACTIVE) ; 
//Check return value 



ISpRecoGrammar::SetRuleIdState activates or deactivates a rule by its RulelD. 

HRESULT SetRuleldState ( 



Example 



© 1995-2000 Microsoft Corporation All rights reserv^ed 
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ISpRecoGrammar: : SetRuleldState 



DWORD 

SPRULESTATE 



dwRuleldf 
News tat e 



); 



Parameters 



dwRuleld 
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dwRuleld 

[in] Value specifying the grammar rule identifier. 
NewState 

[in] Flag of type SPRULESTATE indicating the new rule state. 
Return values 

Value Description 

S_OK Function completed successfully. 

FAILED(hr) Appropriate error message. 

Examples Using This Method 



SDK: Coffee2. 
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ISpRecoGrammar : :LoadDictation 

ISpRecoGrammar::LoadDictation loads a dictation grammar for an engine. 

HRESULT LoadDictation ( 

const WCHAR *pszTopicName , 
SPLOADOPTIONS Options 

); 

Parameters 

pszTopicName 

[in, optional, string] The string containing the topic name. May be set to NULL. SAPI 
defines SPTOPIC^SPELLING 

Options 

[in] Flag of type SPLOADOPTIONS indicating whether the file should be loaded 
statically or dynamically. This value must be SPLO_STATIC, 

Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG pszTopicName is invalid or bad. Alternatively, Options 

is not SPLO_STATIC. 

FAILED(hr) Appropriate error message. 

©_1 995:2000 Microsoft Corporation AH rights reserved 
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ISpRecoGrammar: rUnloadDictation 



ISpRecoGraininar::UnloadDictation unloads a dictation grammar from an engine. 

HRESULT UnloadDictation ( void ) ; 
Parameters 

None. 

Return values 

Value Description 

S_OK Function completed successfully. 

FAILED(hr) Appropriate error message. 



ISpRecoGrammar: : SetDictationState 



ISpRecoGrammar: rSetDictationState sets a dictation state to either active or inactive. 

HRESULT SetDictationState ( 

SPRULESTATE NewState 

); 

Parameters 

NewState 

[in] Flag of type SPRULESTATE indicating the nev^ state of dictation. 
Return values 

Value Description 

S_OK Function completed successfully. 

E INVALIDARG NewState is not an acceptable value. 

SPERR_UNINITIALIZED A dictation is not currently loaded. 

FAILED(hr) Appropriate error message. 



ISpRecoGrammar: : SetWordSequenceData 



© J 995jr2000Mcrosoit Co^ Aljjights reserved 
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ISpRecoGrammar::SetWordSequenceData 



ISpRecoGrammar::SetWordSequenceData sets a word sequence buffer in the SR engine. 
The CFG grammar can refer to any subsequence of words in this buffer using the 
<TEXTBUFFER>tag. 



HRESULT SetWordSequenceData( 
WCHAR *pText, 
ULONG cchText, 

cons t SPTEXTS ELECT I ONINFO Opinio 



Parameters 



pText 

[in] Buffer containing the text to search for possible word sequences. The buffer is 
double-NULL terminated. If the buffer contains *\0* between words, the sub-sequence 
cannot contain words on either side of the '\0'. It is up to the SR engines to perform word 
breaking and text normaUzation for better performance, (See me for an example), 

cchText 

[in] The number of characters (WCHAR) in pText. 

pinfo 

[in] Address of the SPTEXTSELECTIONINFO structure that contains the selection 
information. 



Return values 



Value Description 

S_OK Function completed successfully. 

E_INVALIDARG One or more arguments are invalid. 

FAILED(hr) Appropriate error message. 



© 1995-2000 Microsoft CoiDoration. AW rights reserved 
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ISpRecoGrammar::SetTextSelection 

ISpRecoGrammar::SetTextSelection sets the current text selection and insertion point 
information. 

HRESULT SetTextSelection( 

const SPTEXTSELECTIONINFO *pInfo 

); 

Parameters 

pInfo 

[in] Address of the SPTEXTSELECTIONINFO structure that contains the text selection 
and insertion point information. 
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and insertion point information. 



Return values 



Value 

S_OK 

E_INVALIDARG 
FAILED(hr) 



Description 

Function completed successfully. 
One or more arguments are invalid. 
Appropriate error message. 



©. 1 995-2000 Microsoft Ctyporation^ AH rights reserved. 
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ISpRecoGrammar : ilsPronounceable 



ISpRecoGrammarrrlsPronounceable calls the engine object to determine if the word has a 
pronunciation. 

HREStJLT IsPronounceable { 
const WCHAR *pszWord, 
BOOL pfPronounceabl e 

); 

Parameters 



[in, string] The word to test. Length must be equal to or less than 
SP_MAX_WORD_LENGTH. 
pfPronounceable 

[out] Flag indicating the results of the test. TRUE, if a pronunciation was fovtnd; 
otherwise, FALSE. 

Return values 

Value Description 

S_OK Fimction completed successfully. 

EPOINTER Either pszWord or pfPronounceable is invaUd or bad. 

FAILED (hr) Appropriate error message. 



pszWord 
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ISpRecoGrammar: iSetGrammarState 



ISpRecoGrammar: :SetGrammarState sets the grammar mode. 
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If eGrammarState is SPGM_DISABLED, then SAPI will remember the current rule activation 
state, so that when the grammar state is set to SPGM ENABLED, it restores the grammar rules 
back to each of the original activation states. While the grammar is set to SPGM DISABLED, 
the application can still activate and deactivate rule. The effect is not communicated to the SR 
engine (but remembered by SAPI) until the grammar is enabled again. 

If eGrammarState is SPGM_EXCLUSIVE, then SAPI will disable all other grammars in the 
system, unless another grammar is already exclusive. Activation and deactivation commands 
are buffered for all other grammars xmtil the exclusive grammar is set to SPGM_ENABLED 
again. 



HRESXJLT SetGraimnarState ( 

SPGRAMMARSTATE eGrawmarSta te 

); 

Parameters 

eGrammarState 

[in] Flag of type SPGRAMMARSTATE indicating the new state of the grammar. 
Return values 

Value Description 

S_OK Function completed successftilly. 

FAILED(hr) Appropriate error message. 



ISpRecoGrammar::SaveCmd allows applications using dynamic grammars to save the 
current grammar state to a stream. 



HRESULT SaveCmdC 

IStream *pSaveStream, 



); 

Parameters 

pSaveStream 

[in] The stream to save. 
ppCoMemErrorText 

[out] Optional parameter of a null-terminated string containing error messages that 

occurred during the save operation. 



© 1 995:2000 Microsoft Corporation All rights reserved. 
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ISpRecoGrammar: rSaveCmd 



WCHAR 



* * PpCoMemErrorText 
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Return values 



Value 

S_OK 

E INVALIDARG 



Description 

Function completed successfully. 
pSaveStream is invalid or bad. 



SPERR_NOT_DYNAMIC_GRAMMAR Connnand was loaded but compiler is not 

available. 



SPERR_UNINITIALIZED 
E_POINTER 
FAILED (hr) 



Microsoft Speech SDK 
with SAPI 5.0 



Compiler is not available. 
ppCoMemErrorText is invaUd or bad. 
Appropriate error message. 
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ISpRecoResult 

Note: This interface inherits from ISpPhrase. 



ISpRecoResult Methods 
GetGrammarld 

GetResultTimes 

GetAlternates 
GetAudio 

SpeakAudiq 

Serialize 

ScaleAudio 

GetRecoContext 



Description 

Retrieves the grammar identifier associated with a 
result. 

Retrieves the time information associated with the 
result. 

Retrieves an array containing alternate phrases. 

Creates an audio stream for a given number of 
elements. 

Plays the audio associated with a given range of 
elements. 

Creates a serialized copy of the recognition result 
object. 

Converts the format of the retained audio to a different 
audio format. 

Returns the recognition context object that is 
associated with Ais result. 
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ISpRecoResult: : GetGrammarld 
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ISpRecoResult::GetGrammarId retrieves the grammar identifier associated with a result. 

HRESULT GetGrainmarId{ 

DWORD_PTR *pdwpQrainmarId 

); 

Parameters 

pdwpGrammarld 

[out] Address of the result grammar identifier. 

Return values 

Value Description 

S_OK Function completed successfully. 

E^POESfTER pdwGrammarld is invalid or bad. 



ISpRecoResult::GetResultTimes retrieves the time information associated with the result. 

HRESULT GetResultTimes ( 

SPRECORESULTTIMES ^pTimes 

); 

Parameters 

pTimes 

[out] Address of the SPRECORESULTTIMES data structure containing the time 
information associated with the result. 

Return values 

Value Description 

S_OK Function completed successfully. 

E_POINTER pTimes is invalid or bad. 

SPERR_NOT_FOUND Interface not found. 

Examples Using This Method 

SDK: Coffee2, Coffee3, Coffee4. 



SPERR NOT FOUND 



Interface not found. 
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ISpRecoResult: : GetResultTimes 
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ISpRecoResult: : Get Alternates 

ISpRecoResult::GetAIternates retrieves an array of pointers to ISpPhraseAlt objects 
containing alternate phrases. 



HRESULT GetAlternates ( 

ULONG ulStartElement f 

XJLONG cElements, 
ULONG ulReguestCount f 

ISpPhraseAlt * *ppPhrases , 
ULONG "^pcPhrasesRe turned 



Parameters 

ulStartElement 

[in] The starting element to consider for the alternates. 
cElements 

[in] The number of elements to consider. All elements may be requested by using the 
enumeration value SPPR_ALL_ELEMENTS of type SPPHRASERNG , 

ulRequestCount 

[in] The number of requested alternate phrase elements. 

ppPhrases 

[out] Address of an array of ISpPhraseAlt interface pointers that will contain the 
alternate phrases. The elements between the start of the ulStartElement element and the 
end of the ulStartElement and cElements element combined is the portion that will 
change. The rest of the elements will be included in each alternate phrase, 
pcPhrasesReturned 

[out] Pointer to a ULONG that receives the actual number of alternate phrases retrieved. 
Return values 



Value Description 

S_OK Function completed successfully. 

E POINTER pcPhrasesReturned is an invalid pointer. However, 

ppPhrases does not contain ulRequestCount 
allocations. 

E_OUTOFMEMORY Exceeded available memory. 

E_INVALIDARG ulStartElement is not less than the number of elements 

in owning interface. However, the number of expected 
elements exceeds the number of available elements in 
the owning interface. 

S_FALSE No analyzer is present or there is no driver data. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation All n^ht? reserved. 
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[This is preliminary documentation and subject to changej ^IP 

ISpRecoResult: : Get Audio 

ISpRecoResult::GetAudio creates an audio stream of the requested words from the audio data 
in the result object. 

Even if there are no elements, that is, ulStartElement = 0 and cElements = 0, then the audio will 
still be played. There are "unrecognized" results that have no elements but do have audio. 

HRESULT GetAudio( 

ULONG ul S tartEl emen t , 

ULONG cEl emen t s , 

ISpStreamFoirmat * *ppStream 

); 

Parameters 

ulStartElement ^ ^ . ^ 

[in] Value specifying from which element in the result data to start the audio stream . 

cElements 

[in] Value specifying the total number of words. 

vpStream ^ , . ^ ^ — 

[out] Address that will receive a pointer to an ISpStreamFor^^^ object containing the 

audio data requested. 
Return values 

Value Description 

3 OK Function completed successfully. 

E~INV ALID ARG cElements is zero or the expected number of elements 

*" to count exceeds the number available. 

E POINTER j^pSfream is an invalid pointer. 

SPERR_NO_AUDIO_DATA This result object does not have any audio data. 

F AILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation All rights resented . 
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ISpRecoResult: : SpeakAudio 

ISpRecoResultf.SpeakAudio is a shortcut, first calling ISpRecoResult: :GetAudio and then 
calling ISpVoice::.SpeakStream on the parent recognition context. 

HRESULT SpeakAudio ( 

ULONG UlStartElement, 
ULONG cElemsnts, 
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DWORD dwFlags, 

ULONG *pulSt reamNumber 

); 

Parameters 

ulStartElement 

[in] Value specifying with which element to start. 

[in] Value specifying the number of elements contained in the stream. A value of zero 
speaks all elements. 

dwFla^^ Value containing flag information associated with audio elements. 
pulStreamNumber 

[out] Address of a variable containing the stream number mformation. 

Return values 

Value Description 

S OK Function completed successfully. 

SPERR_NO_AUDIO_DATA Result does ncrt contain audio data. 

FAILED(hr) Appropriate error message. 

Note: Return values may also be the same as ISpVoiceiiSpeakStrea^ 

©J 995-2000 Microsoft_Corporati^^^ All jights reserved. 
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ISpRecoResult: : Serialize 

ISpRecoResult::Serialize creates a serialized copy of the recognition result object. The 
serialized copy can be saved and later restored using the ISpRecpContext: :Deseria 
method. 



HRESULT Serialize { 

SPSERIALIZEDRESULT **ppCoMemSerj.alizedResult 

); 

Parameters 

pvCoMemSerializedResult ^ . . 

[outl Address of a pointer to the SPSERIALIZEDRESULT structure that receives the 
serialized result information. Call CoTaskMemFree() to free the memory associated with 
the serialized result object. 

Return values 

Value Description 

S OK Fimction completed successfully. 
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E POINTER ppCoMemSerializedResult is an invalid pointer. 

E_OUTOFMEMORY Exceeded available memory. 

FAILED(hr) Appropriate error message. 



© 1995-2000 Microsoft Corporation. All rights resented . 
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ISpRecoResult: : Scale Audio 

ISpRecoResult::ScaleAudio converts an existing audio stream into a different audio format. 
Use the ISpPhrase::Discard method to completely discard audio data associated with a result 
object. 



HRESULT ScaleAudio( 

const GUID *pAudioFoiJnatId, 
const WAVSFORMATEX *pWaveFormatEx 

); 

Parameters 

pAudioFormatId 

[in] Address of the data format identifier. Typically, this value is 

SPFIDJVaveFormatEx, 
pWaveFormatEx ^ . , _ 

[in] Address of the WAVEFORM ATEX structure that contains the audio format to 

convert to. 

Note: This value must be NULL if pAudioFormatId is not specified as 
SPFIDJVaveForamtEx. 

Return values 

Value Description 

S OK Function completed successfully. 

EINVALIDARG Either pAudioFormatId or pWaveFormatEx is invalid 

~ or bad. 

SPERR NO_AUDIO_DATA Either ulPhrases is zero or an audio stream is 

~ unavailable. 

E OUTOFMEMORY Exceeded available memory. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation All rights reser\'ed 
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ISpRecoResult: :GetRecoContext 
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ISpRecoResult::GetRecoContext returns the recognition context object this result object is 
associated with. 



HRESULT GetRecoContext ( 

ISpRecoContext ^-^^ppRecoContext 

); 

Parameters 

ppRecoContext 

[out] A pointer that receives the recognition context interface pointer. 
Return values 

Value Description 

S OK Function completed successfully. 

E POINTER ppRecoContext IS 'mwdi^iA or hdd. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft CoTporatipn„ A!l_ri^hts reserved 
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with SAPI 5.0 ^ 

[This is preliminary documentation and subject to change.] 

ISpRecognizer 

The ISpRecognizer interface enables appUcations to directly control aspects of the speech 
recognition (SR) engine. 

When to Use 

Call methods of the ISpRecognizer interface to configure or retrieve the attributes of the SR 
engine. 

Note: Not all functionality will be available in the shared instances. 
Note: This interface inherits from ISpProperties. 
Methods in Vtable Order 

ISpRecognizer Methods Description 

SetRecognizer Specifies an SR engine. 

GetRecognizer Retrieves an SR engine. 

Setlnput Enables an application to specify which input stream 

the SR engine should use. 
GetlnputObjectToken Retrieves the input token object for the stream. 
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GetlnputObjectToken 


Retrieves the input token object for the stream. 


GetlnputStream 


Retrieves the input stream. 


CreateRecoContext 


Enables an application to create a recognition context 




for this instance of an SR engine. 


GetRecoPrqfile 


Retrieves a pointer to the recognition profile token. 




Slpt<i tVip "nrnfilp infnTTnf*tinn nf tVip rprncrnitinii "nrnfilp 




token. 


IsSharedlnstance 


Determines if the SR engine is currently shared by 




other contexts. 


GetRecoState 


Retrieves the state of the recognition engine. 


SetRecoState 


Sets the state of the recognition engine. 


GetStatus 


Retrieves the current input status for the engine. 




T^pfripvpc flip fntTHfii" iTiff^tmJifinti 5i<i<inf*iPitpH witTi tHp 

rvClllCVCo Uiv lUiiiiu.1 11.11 VJiliiilLlUll dadUUlul^U WlLll llli^ 




audio stream. 


IsUISupported 


Checks if the underlying tokens support the requested 


user interface. 


DisglayUI 


Displays the user interface from the underlying tokens. 


EmulateRecogm^ 


Emulates a recognition from a specified phrase rather 


than from spoken content. 



p 1995-2000Jy1icrosoft CqrpOTatiqn^^^^^ rights reserved. 
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ISpRecognizer : :SetRecognizer 

ISpRecognizer::SetRecognizer specifies a speech recognition engine. 



HRESULT SetRecognizer ( 

ISpObj ectToken *pEngineToken 

); 

Parameters 

pEngineToken 

[in] The desired speech recognition engine. 

Return values 



Value Description 

S DK Function completed successfully. 

E_INVALIDARG pEngineToken is invalid or bad. 

SPERR_ALREADY_INITIALIZED Interface is already initialized. 
EJSfOTIMPL Method is not available in the shared instance. 

FAILED(hr) Appropriate error message. 
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ISpRecognizer : :GetRecognizer 

ISpRecognizerr.GetRecognizer retrieves a speech recognition engine. 

HRESULT GetRecognizer ( 

ISpOb j ectToken **ppEngineToken 

); 

Parameters 

ppEngineToken 

[out] The retrieved speech recognition engine. 

Return values 

Value Description 

g Function completed successfully. 

E INVALID ARG ppEngineToken is invalid or bad. 

FAILED(hr) Appropriate error message. 



© 1995-2000 Microsoft Corporation. All rights reserved . 
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ISpRecognizer : rSetlnput 

ISpRecognizer: :SetInput enables an application to specify which input stream the SR engine 
should use. 

If the engine is currently processing audio, this call will fail. 

HRESULT Setlnput( 

lUnknown *pUnkInputr 

BOOL fAl 1 owForma tChanges 

); 

Parameters 

pUnklnput 

[in] The stream object token. 
fAUowFormatChanges ^ t • j ^^oTTr: n 

[in] Boolean indicating an existing format may be converted if required. TRUb allows 
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[in] Boolean indicating an existing format may be converted if required. TRUE allows 
the format conversion; otherwise, FALSE. 



Return values 

Value 

S_OK 

E_INVALIDARG 
SPERR_ENGINE_BUSY 

FAILED(hr) 



Description 

Function completed successfully. 

pUnklnput is invalid or not a stream. 

The current method can not be performed while a 

grammar rule is active. 

Appropriate error message. 

© 1 995-20^00 Microsoft Cpjporatipn _ All.rights reserved. 
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ISpRecognizer : : GetlnputObj ectToken 

ISpRecognizer::GetInputObjectTokeii retrieves the input token object for the stream. 

HRESULT GetlnputObj ectToken ( 

ISpObj ectToken **ppToken 

) } 



Parameters 




ppToken 




[out] The input token pointer 




Return values 




Value 


Description 


S_OK 


Function completed successfully. 


S_FALSE 


Function completed successfully, but there was no 




input or the input has no token. 


E_POINTER 


ppToken is invalid or bad. 


E_NOTIMPL 


Method is not available in the shared instance. 


FAILED(hr) 


Appropriate error message. 



©1995-2p00_Micrpspft^Corporation All righte reserved 



[This is preliminar>' documentation md subject to change.] 

ISpRecognizer: -.GetlnputStream 

ISpRecognizer: rGetlnputStream retrieves the input stream. 
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HRESULT 6e t Inputs tr earn ( 

I Sp S t r eamForma t * *pp5 tream 

) ; 

Parameters 

ppStream 

[out] Address of a pointer to the ISpStreamFqrmat object that receives the input stream 
information. 

Return values 

Value Description 

S_OK Function completed successfully. 

E_POINTER ppStream is invalid or bad. 

SPERR__NOT__FOUND ppStream is not initialized. 

E__NOTIMPL Method is not available in the shared instance. 

FAILED(hr) Appropriate error message. 



ISpRecognizer::CreateRecoContext enables an application to create a recognition context for 
this instance of an SR engine. 

HRESULT CreateRecoContext { 

I SpRec oCon t ext * *ppNewCon text 

) ; 

Parameters 

ppNewContext 

[out] Address of a pointer to an ISpRecoContext interface receiving the recognition 
context. 

Return values 

Value Description 

S_OK Function completed successfully. 

E__POINTER ppNewContext is invalid or bad. 

FAILED(hr) Appropriate error message. 

Examples Using This Method 



© 1995-2000 Microsoft Corpor ation All rights reserved 
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ISpRecognizer : : CreateRecoContext 
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SDK: CoffeeO; Coffee 1; Cofifee2. 



© l?95-20p_0 Microspft_Cpiporation. _AI1 rights resented 
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ISpRecognizer : :GetRecoProfile 



ISpRecognizer::GetRecoProfile retrieves a pointer to the recognition profile token. 

HRESULT GetRecoProf ile ( 

ISpOb j ec tToken * *ppToken 

); 

Parameters 

ppToken 

[out] Address of a pointer of an ISpObjectToken that receives the profile information. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG One or more arguments are invalid. 

FAILED(hr) Appropriate error message. 



ISpRecognizer: iSetRecoProfile sets the profile information of the recognition profile token. 

HRESULT SetRecoProf ile ( 

I SpObjec tToken *pToken 

); 

Parameters 

pToken 

[in] Address of an ISpObjectToken object that contains the profile information 
Return values 

Value Description 

S_OK Function completed successfully. 



P.l^?5-2000 Microsoft CoTppratioa AU rights reserved 
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ISpRecognizer : :SetRecoProfile 
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S_OK Function completed successfully. 

FAILED(hr) Appropriate error message, 

E_INVALIDARG One or more arguments are invalid. 

© ]^?95-20pO Microsoft Corporation Ail rights reserved. 

[This is preliminary documentation and subject to change.] 

ISpRecognizer : ilsSharedlnstance 

ISpRecognizer::IsSharedInstance determines if the SR engine is currently shared by other 
contexts. 

HRESULT IsSharedlnstance { void ) ; 
Parameters 

None. 

Return values 

Value Description 

S_OK Indicates that this instance of the recognition engine is 

being shared. 

S_FALSE Indicates that this instance of the recognition engine is 

not being shared. 

© 1995:2000 Microsoft Cprf>orat3on_AlJ nghts_reserved. 

[This is preliminary documenlation and subject to change.] 

ISpRecognizer: :GetRecoState 

ISpRecognizer::GetRecoState retrieves the current state of the recognition engine. 

HRESULT GetRecoState ( 

SPRECOSTATE *pState 

); 

Parameters 

pState 

[out] One of the input state flags contained in the SPRECOSTATE enumeration. 
Return values 

Value Description 
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S_OK 

E_POINTER 
FAILED(hr) 



Function completed successfully. 
Invalid pointer. 
Appropriate error message. 



© 1995-2000 Micxospft Corporatiqri^ AlllM^.tsieserved. 
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ISpRecognizer : : SetRecoState 



ISpRecognizerxSetRecoState sets the state of the recognition engine, 

HRESULT SetRecoState ( 

SPRECOSTATB NewState 

); 

Parameters 

NewState 

[in] One of the flags contained in the SPRECO S T ATE enumeration. 
Return values 

Value Description 

S OK Fimction completed successfully, 

FAILED(hr) Appropriate error message. 

E_INVALIDARG One or more arguments are invalid. 



ISpRecognizer: :GetStatus gets the current input status for the engine. 

HRESULT GetStatus( 

SPRECOGNIZSRSTATUS *pStatu3 

); 



Parameters 



pStatus 

[out] The current input status of the engine. 
Return values 



© l_995-2000 Microsoft Coi^iorapon AjL-D&^ts resented 
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ISpRecognizer: :GetStatus 
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Value Description 

S_OK Function completed successfully. 

E_POINTER pStatus is invalid or bad. 



© 1995-2000 MLcro_softCo^^ rights reserved. 



[This is prelimiiiaty documentation and subject to change.] 

ISpRecognizer : iGetFormat 

ISpRecognizer::GetFormat retrieves the format information associated v^ith the audio stream. 

HRESULT GetFormat( 

SPSTREAMFORMATTYPE V^aveForma tType , 
GUID" ^pFoijnatld, 
WAVEFORMATEX * * ppCoMemWFEX 

) ; 

Parameters 

WaveFormatType 

[in] One of the wave file format types specified in SPSTI^AMFORMATTO 
pFormatId 

[out] The address of the unique identifier associated with the format type. 
ppCoMemWFEX 

[out] Address of a pointer to a WAyEFORMATEX structure that receives the format 
information. 

Return values 

Value Description 

S_OK Fimction completed successfiilly. 

E_POINTER Invalid pointer. 

F AILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation. AU rights reseryed. 



[This is preliminary documentation and subject to change.] 4£ 

ISpRecognizer : rIsUISupported 

ISpRecognizer::IsUISupported checks if the underlying tokens support the requested UL 

[local] HRESULT IsUISupported ( 
const WCHAR -^pszTypeOfUJ , 
void pvExtraData r 

tJLONG cbEKtraDa t a , 
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BOOL *pf Supported 

); 

Parameters 

pszTypeOfUI 

[in] Address of a pointer to a nuU-terminated string containing the UI type information. 
pvExtraData 

[in] Additional information for the call. 
chExtraData 

[in] Size, in bytes^ of pvExtraData. 
pfSupported 

[out] Address of a variable that receives the value indicating support for the interface. 
This value is set to TRUE when this interface is supported; otherwise set to FALSE. 

Return values 

Value Description 

S_OK Function completed successfully. 

E_INV ALIDARG pfSupported is invalid or bad. 

FAILED(hr) Appropriate error message. 

©J 995-2000 Micro_spft Corporation AU rights reserved. 



[This is prelimiiiar}' documentation and subject to change.] 

ISpRecognizer : :DisplayUI 

ISpRecognizer::DisplayUI displays the UI from the underlying tokens. 

[local] HRESULT DisplayUI ( 

HWND hwndParen t , 

const WCHAR *pszTltlef 

const WCHAR *pszTypeOfUI , 

void *pvExtraData, 

ULONG cbExtraDa ta 

); 

Parameters 

hwndParent 

[in] Specifies the handle of the parent window. 
pszTitle 

[in] Address of a null-terminated string containing the window title. 
pszTypeOfUI 

[in] Address of a null-terminated string containing the UI type information. 
pvExtraData 

[in] Additional information for the call 
cbExtraData 

[in] Size, in bytes, of the contents of pvExtraData. 
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Return values 



Value 



Description 

Function completed successfully. 
Appropriate error message. 



S OK 



FAILED(hr) 



© L995-20P0 Mjcrosoft_^Corporatioa AH. risi»^-„ceseryecl. 



[This is preliminan'' documentation and subject to change,] 



1^ 



ISpRecognizer::EmulateRecognition 



ISpRecognizer::EmulateRecognition emulates a recognition from a specified phrase rather 
than from spoken content. This method generates a recognition event only if the entire sentence 
parsed. 



HRESULT EmulateRecognition ( 

I Sp Phrase *pPhrase 

) ; 

Parameters 

pPhrase 

[in] The phrase to emulate. 

Return values 

Value Description 

S_OK Function completed successfiiUy. 

E POINTER ppCoMemPhrase is invalid or bad. 



SPERR_UNINITIALIZED 

E^OUTOFMEMORY 

FAILED(hr) 



Phrase is uninitialized. 
Exceeded available memory. 
Appropriate error message. 



©1995-2000 Microsoft Cprppration All rightsjeserved 



IVIicrosoft Speech SDK 
with SAPI 5.0 




[This is prcliniinary documentation and subject to change.] 



ISpPhrase 



Methods in Vtable Order 



ISpPhrase Methods 



Description 
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GetPhrase 
GetSerializedPhrase 



GetText 
Discard 



Retrieves data elements associated with a phrase. 

Retrieves a memory block containing all of the data 
for this phrase. 

Retrieves elements from a text phrase. 

Discards the requested data from an individual 
element. 



P. Ii?5:2000 Microsoft Co^wratipn^All r!^hts_res_eiyed. 



[This is preliminary^ documentation and subject to change,] 




ISpPhrase: : GetPhrase 



ISpPhrase::GetPhrase retrieves data elements associated with a phrase. 

HRESULT GetPhrase ( 

SPpURASE * -^ppCoMemPhrase 

); 

Parameters 

ppCoMemPhrase 

[out] Address of a pointer to a SPPHRASE data structure receiving the phrase 
information. May be NULL if no phrase is recognized. If NULL, no memory is allocated 
for the structure. 

Return values 

Value Description 

S_OK Function completed successfully. 

E_POINTER Invalid pointer. 

E_OUTOFMEMORY Exceeded available memory. 

Note: 

Returned data includes all elements associated with this phrase. 



ISpPhrase:: GetSerializedPhrase passes back a memory block containing all of the data for 
this phrase. 



© 1995-2000 Microsoft Corpo rati on AH rights TQserved 
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ISpPhrase: : GetSerializedPhrase 
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This is a serialized version of SPPHRASE . It allocates a continuous block of memory and uses 
offsets instead of pointers and fills in the block. It also reports the total number of bytes it 
occupies after serialization in SPSERIALIZEDPHRASE . This allows the text to be written to 
the disk safely. However, make a critical section lock for the phrase object before making this 
call. 



HRESULT GetSerializedPhrase ( 

SPSERIALIZBDPHRASE **ppCoMemPhrase 

;) 



Parameters 



ppCoMemPhrase 

[out] Address of a pointer to a SPSERIALIZEDPHRASE data structure receiving the 
phrase information. 



Return values 



Value 

S_OK 

E_POINTER 

SPERR_UNINITIALIZED 
E OUTOFMEMORY 



Description 

Function completed successfully. 
ppCoMemPhrase is invalid or bad. 
Phrase is uninitialized. 
Exceeded available memory. 



© 1995:2000 Microsoft Corporation^. AJl ri^^ts reserved. 



[This is preliminary documentation and subject to change J 

ISpPhrase.rGetText 

ISpPhrase::GetText retrieves elements from a text phrase. 

HRESULT GetText( 

ULONG ulStart, 

ULONG ulCount, 

BOOIi fUseTextReplacements, 

WCHAR -^^ppszCoMemText, 

BYTE *pbDi splayAt tribu tes 

); 

Parameters 

ulStart 

[in] Specifies the first element in the text phrase. 
ulCount 
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[in] Specifies the number of elements to retrieve from the text phrase. 
fUseTextReplacements 

[in] Boolean value that indicates if replacement text should be used. 

ppszCoMemText . t i- i • r 

[out] Address of a pointer to the data structure that contams the display text intormation. 

pbDisplayAttributes 

[out] Address of the SPDISPLAYATTRIBUTES enumeration that contains the text 
display attribute information. 



Return values 

Value 

S_OK 
S_FALSE 

E_INVALIDARG 

E_POINTER 

E OUTOFMEMORY 



Description 

Function completed successfully. 

A phrase that does not contain text or ppszCoMemText 

is NULL. 

One or more arguments are invalid. 

Invalid pointer. 

Exceeded available memory. 

© 1995-2000 Microsoft Coippiatjpn .All ri^hts_reserved. 



[This is preliminary documentation and subject to change.] 

ISpPhrase: :Discard 

ISpPhrase::Discard discards the requested data from an individual element. 
This function sets the string pointers to NULL but does not reallocate the structure, 

ULONG Discard { 

DWORD d-wValueTypes 

;) 

Parameters 

dwValueTypes ^ . . r ^ n ^^ 

[in] Flags of type SPVALUETYPE must be one or a combmation of the following 

values: 



Value 

SPDF_DISPLAYTEXT 
SPDF_LEXICALFORM 
SPDF PRONUNCIATION 



Description 

Removes the display text. 
Removes the lexicon from text. 
Removes the pronunciation text. 



Return value 

The number of characters discarded. 



) 1995-2000 Microsoft Corporation. Ail rights reserved 
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Microsoft Speech SDK 



with SAPI 5.0 ^ ^ W 

[This is preliminaty documentation and subject to change.] 

ISpPhraseAlt 

Note: The ISpPhraseAlt interface inherits from ISpPhrase , 
Methods in Vtable Order 
ISpPhraseAlt Methods Description 

GetAltlnfo Retrieves data elements associated with an alternate 

phrase. 

Commit Replaces the section of the phrase that presents the 

best match to this alternate phrase with the contents of 
the alternate phrase. 

© 1 995-20_00 Microsoft Corporation ^ All rights reserved. 

[This is preliminary documentation and subject to change.] 

ISpPhraseAlt: :GetAltInfo 

ISpPhraseAlt: rGetAitlnfo retrieves data elements associated with an altemate phrase. 

HRESULT GetAltlnfo ( 

ISpPhrase **ppParent, 
ULONG *pulStartElementInParent , 

ULONG *pcEl ementsInParen t , 

ULONG *p cEl emen tsInAl t 

); 

Parameters 

ppParent 

Address of a pointer to the ISpPhrase object receiving the altemate text phrase 

information, 
pulStartElementlnParent 

Value that receives the first element in the text phrase of the parent object. 
pcElementsInParent 

Value that receives the total number of text phrase elements in the parent object. 

pcElementsInA It 

Value that receives the total number of elements associated with the altemate text phrase. 
Return values 

Value Description 

S OK Function completed successfully. 
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E__POINTER 
E_INVALIDARG 
SPERR_NOT_FOUND 
FAILED(hr) 



ppvObject is invalid or bad. 
One of the parameters is invalid or bad. 
One of the interfaces is invalid or bad. 
Appropriate error message. 



1995-2000 Microsoft CpiporaU^^^ AJljish^. /^served 
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ISpPhraseAlt: : Commit 



ISpPhraseAltirCommit replaces the section of the phrase that presents the best match to this 
alternate phrase with the contents of the alternate phrase. 

When the best phrase is subsequently received from the result object instance, the updated 
phrase will be returned rather than the phrase originally chosen by the recognizer. This method 
also updates the generation identifier of the phrase. 

HRESULT Commit ( void ) ; 
Parameters 

None 

Return values 

Value Description 

S OK Function completed successfully. 

SPERRNOT^FOUND One of the interfaces is invalid or bad. 

FAILED(hr) Appropriate error message. 



1 995_-2000_M Lcrosoft Corporato AJl Jishls reserved 



Microsoft Speech SDK 
with SAPI 5.0 




[This is preliminar}^ docimientation and subject to change.] 



ISpProperties 



ISpProperties sets and retrieves property attribute information. 



Methods in Vtable Order 



ISpProperties Methods 
SetPropertyNum 



Description 

Sets the numeric attribute property information of the 
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recognition engine. 

GetPropet^Num Retrieves the numeric attribute property information 

of the recognition engine. 

SetPropert yString Sets the text attribute property information of the 

recognition engine. 

GetPrppertySt™ Retrieves the text attribute property information of the 

recognition engine. 

© 1995-2000 Mtcrosoft Corporatiojfi. AU rights reserved 

[This is preliminaiy documentation and subject to change.] 1^ 

ISpProperties : : SetPr opertyNum 

ISpProperties::SetPropertyNum sets the numeric attribute property information of the 
recognition engine. 

HRESULT SetPropertyNum( 
const WCHAR *pName, 
LONG lvalue 

); 

Parameters 

pName 

[in] Address of the string containing the property attribute name information. 
IValue 

[in] Address of the value containing the property attribute value information. 
Return values 

Value Description 

S_OK Function completed successftiUy. 

E_INVALIDARG One or more arguments are invalid. 

E_POINTER Invalid pomter. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Coippration. All rights reserved 



.2.S 



[This is preliminary documentation and subject to change.] 

ISpProperties: :GetPropertyNum 

ISpProperties: iGetPropertyNum retrieves the recognition engine numeric attribute property 
information. 

HRESULT GetPropertyNum{ 
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const WCHAR 
LONG 



*pName, 
*plValue 



); 

Parameters 

pName 

[in] Address of the string containing the property attribute name information. 
pi Value 

[out] Address of the value that receives the property attribute value information. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_IN VALID ARG One or more arguments are invalid. 

E_POINTER Invalid pointer. 

FAILED(hr) Appropriate error message. 



ISpProperties::SetPropertyString sets the text attribute property information of the 
recognition engine. 

HRESULT SetPropertyStringC 
const WCHAR *pName, 
const WCHAR *p Value 

); 

Parameters 



© 1995-2000 Microsoft Corporation All rights reserved . 
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ISpPr operties : : SetProperty String 



pName 



[in] Address of a string containing the property name information. 



pValue 



[in] Address of a string containing the property value information. 



Return values 



Value 

S_OK 

E__INVALIDARG 
FAILED(hr) 



Description 

Function completed successfully. 
One or more arguments are invalid. 
Appropriate error message. 



© 1995:2000 Microsoft Coi3>gradon rights reserved. 
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[This is preliminar}^ documentation and subject to change.] 

ISpProperties: :GetProperty String 

ISpProperties::GetPropertyStringretrieves recognition engine text attribute property 
information, 

HRESULT GetPropertyStriiig( 
const WCHAR *pName, 
WCHAR •^*ppCoMemValue 

) ; 

Parameters 

pName 

[in] Address of a string containing the property name information. 
ppCoMem Value 

[out] Address of the string that receives the property attribute value information. 
The caller must call CoTaskMemFreeQ to free the string pointer. 

Return values 

Value Description 

S_OK Fimction completed successfully. 

E_INVALIDARG One or more arguments are invalid. 

FAILED(hr) Appropriate error message. 



e 1995:2000_Microsoft Corporation, All rights reser^'ed 



Microsoft Speech SDK 
with SAPI 5.0 



[This is preliminar>^ documentation and subject to change] 

SAPI Text to Speech 

The following section covers: 



• Introduction 

• Text synthesis 



ISpVoice 

© 1995-2000 Microsoft Corporati All rights reserved 



[This is prelimtnaiy docmnentation and subject to change,] 

Overview 



file://C:\WIND0WS\TEMPWhh2BlB.htm 



12/28/00 



Application-Level Interfaces 



Page 162 of 199 



Overview 

The following section covers: 

• What is text to speech? 

• Why use texlto spe^^^ 

What is text to speech? 

Text to speech (TTS) is a process through v^hich text is rendered as digital audio and then 
"spoken." Most TTS engines can be categorized by the method they use to translate phonemes 
into audible sound, 

• Concatenated word 

• Synthesis 

• Subword concatenation 
Concatenated word: 

Although concatenated word systems are not really synthesizers, they are one of the most 
commonly used text-to-speech system implementations. In a concatenated word engine, 
the application designer provides recordings for phrases and individual words. The 
engine concatenates the recordings together in order to form one spoken sentence or 
phrase. A voice-mail system most likely uses a concatenated word engine. For example, 
" You have three new messages ." In this example, the engine has recordings for "You 
have", + all of the digits, + "new messages" to form the voice mail interaction phrase. 
Synthesis: 

A text-to-speech engine uses synthesis to generate sounds similar to those created by the 
human vocal cords and applies various filters to simulate throat length, mouth cavity, lip 
shape, and tongue position. The voice produced by synthesis technology tends to soimd 
less human than a voice produced by diphone concatenation, but it is possible to obtain 
different voice qualities by changing a few parameters. 
Subword concatenation: 

A text-to-speech engine uses subword concatenation to link short digital-audio 
segments together and performs inter-segment smoothing to produce a continuous 
sound. In diphone concatenation for example, each segment consists of two phonemes, 
one that leads into the sound and one that finishes the sound. Thus, the word "hello" 
consists of the phonemes, h ™ eh ™ 1 ™ oe. The corresponding subword segments are 
silence-h - h-eh - eh-1 - 1-oe - oe-silence . Subword segments are created by recording 
many hours of a human voice and carefiilly identifying the beginning and ending of 
phonemes. Although this technique can produce a more realistic voice, it takes a 
considerable amount of work to create a new voice and the voice is not easily 
localizable, as the phonemes are specific to the speaker's language. 

a; Back to top 

Why use text to speech? 

Text to speech (TTS) should be used to audibly communicate information to the user, when 
digital audio recordings are inadequate. Generally, text to speech is better than audio 
recordings when: 

• Audio recordings are too large to store on disk or too expensive to record. 

• Audio recording is not possible, as the application doesn't know ahead of time what it 
will speak. 



file://C:\WIND0WS\TEMPWhh2BlB.htm 



12/28/00 



Application-Level Interfaces 



Page 163 of 199 



Text to speech also offers a number of benefits. In general, text to speech is most useful for 
short phrases or for situations when prerecording is not practical. Text to speech has the 
following practical uses: 

• Reading dynamic text 

• ProofreadinR 

• Conserving storage space 

• Notifying the user of events 

• Providing audible feedback 
Reading dynamic text: 

Text to speech is useful for phrases that vary too much to record and store each possible 
alternative. For example, speaking the time is a good use for text to speech, because the 
effort and storage involved in concatenating all possible times is manageable. 
Proofreading: 

Audible proofreading of text and numbers helps catch typing errors missed by visual 
proofreading. 

Conserving storage space: 

Text to speech is useful for phrases that would occupy too much storage space if they 
were prerecorded in digital-audio format. 

Notifying the user of events : 

Text to speech works well for informational messages. For example, to inform the user 
that a print job is complete, an application could say "printing complete" rather than 
displaying a message box and requiring the user to cUck the OK button. 
Note: This should be used for noncritical notifications, as the user may have turned off 
the computer's sound, or may be physically out of hearing range. 

Providing audible feedback: 

Text to speech can provide audible feedback when visual feedback is inadequate or 
impossible. For example, the user's eyes might be busy with another task, such as 
transcribing data from a paper docximent. Users who have low vision could be reliant on 
text to speech as primary feedback mechanism from the computer. 

Back to top 



The following section covers: 

• Introducing the text-to-speech architecture 

• Text-to-speech implementation considerations 

• Application design considerations 

Introducing the text-to-speech architecture 

SAPI 5.0 compliant applications use the ISpVoice interface methods to access and control the 
text-to-speech features. 

The ISpVoice interface Speak method is used to create the synthesized output of the engine. 



©1995-2000 Microsoft Corporation _ AUrights resented. 
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Introduction 
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SAPI 5.0 compliant applications can speak synchronously or asynchronously. It is possible to 
have the speak call speak text files and mix TTS synthesis text with audio files. Applications 
select text-to-speech voices by implementing the ISpVoice interface SetVoice method. 

SAPI 5.0 enables the Extensible Markup Language (XML) to configure the settings for state of 
the voice (characteristics such as rate, pitch, and speed). AppUcations can use XML when 
calling the ISpVoice interface Speak method. Voices can be assigned different priorities usmg 
the ISpVoice: rSetPriority, and voices with a higher priority will interrupt a voice with a lower 
priority. AMtionai mformation about SAPI 5.0 XML tagging is located at Text synthesis. 

Application drivers for the SAPI speech synthesis (text to speech) engine implement the 
ISpTTSEngine interface. The primary method called by SAPI to perform speech rendering is 
i'SpTf SEngine::Speak. SAPI, rather than the engine, performs XML parsing of the input text 
sti-eam. The engine's Speak method is handed a linked list of text fi-agments with their 
associated XML attribute states. The Speak method also receives a pointer to the ISpVoice's 
ISpTTSEngineSite interface. The TTS engine uses this interface to queue events and to write 
output data. 

Although SAPI 5.0 is a fi-ee-threaded architectiire, instances of the TTS engine will alvvays be 
called by SAPI on a single thread. TTS engines are never directiy accessed by applications. 



X Back to top 



Text-to-speech implementation considerations 

The following section covers: 

• Text-to-speech voice quality 

• Creating and jpcalizing^texM^ 

• Regi_sJerin^_text4o-speech voices 
Text-to-speech voice quality 

Most text-to-speech (TTS) engines can render individual words successfiiUy. However, 
as soon as tiie engine speaks a sentence, it is easy to identify the voice as synthesized 
because it lacks human prosody (i.e., the inflection, accent, and timing that is commonly 
present in human speech communications.) For this reason, text-to-speech voices are 
often difficult to listen to and require concentration to understand, especially for more 
than a few words at a time. 



Some TTS engines allow an application to define TTS segments with human prosody 
attached, making the synthesized voice much clearer. The engine provides this capability 
by pre-recording a human voice and allowing tiie application developer to transfer its 
intonation and speed to the text being spoken. 

In effect, this acts as a highly effective voice compression algorithm. Although text with 
prosody attached requires more storage than ASCII text (approximately 1 kilobyte per 
minute compared to a few hundred bytes per minute), it requires considerably less 
storage than pre-recorded speech, which requires at least 30 kilobytes per minute. The 
following list of TTS factors also influence the quality of a synthesized voice: 



o Emotion: 

Although many TTS engines can parse and interpret punctuation, such as penods, 
commas, exclamation points, and questions, none of the engines that are currently 
available can render the sound of human emotion. 
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o Mispronunciation: 

Text-to-speech engines use a set of pronunciation rules to translate text into 
phonemes. This is fairly easy for languages with phonetic alphabets, but it is very 
difficult for the English language, especially if last names are to be pronounced 
correctly. (Pronunciation rules seldom fail on common words, but often yield 
unsuccessful results on names that are unusual or of non-English origin.) 



Creating and localizing text-to-speech voices 

Creating a new voice for an engine that uses synthesis can be done relatively quickly by 
altering a few parameters of an existing voice. Although the pitch and timbre of the new 
voice are different, it uses the same speaking style and prosody rules as the existing 
voice. 

Creating a new voice for a TTS engine that uses diphone concatenation can take a 
considerable amount of work. This is because the diphones must be acquired by 
recording a human voice and identifying the beginning and ending of phonemes, which 
are specific to the speaker's language. 

Whether a text-to-speech engine uses synthesis or diphone concatenation, the work of 
localizing an engine for a new language requires a skilled linguist to design 
pronunciation and prosody rules and reprogram the engine to simulate the sound of the 
language's phonemes. In addition, diphone concatenation systems require a new voice to 
be constructed for the new language. As a result, most engines support only five to ten 
major languages. 

Registering text-to-speech voices 

In order to register a new voice, the user will need to specify the CLSID (Class ID). This 
specifies the object that is created when the ISp Voice object is created. For example, this 
could be the engine in the text-to-speech development environment. 

In the registry, the Microsoft TTS Voices have a VoiceData and a VoiceDef field. These 
are proprietary fields that are specific to the Microsoft engine and define where the voice 
data are located. These can be changed to company specific proprietary names. These 
values are accessible from the engine upon creation using the SetObjectToken method. 

The Attributes field contains information associated with the TTS engine. However, in 
the SAPI 5.0 release the properties of this field have not been completely defined. It is 
important that the word "Default" appear as one of the registered voices. Microsoft has 
not specified the type of information, or the format of this field. Thus, all information 
associated with this field is subject to change in a future release. The locale name (LCID) 
of the voice is 409 and is intended for UI purposes only. 

Engine developers are required to register the voices for their engine and include the 
following four fields in the registry: 

1 . Default The default voice for the engine. 

2. 409 The engine name as displayed in the locale identifier (LCID). 

3. Attributes The text string containing the TTS engine voice information. 

4. CLSID The class identifier (CLSID) for the TTS engine. 

While it is possible to store other engine specific information within the registry, the 
above entries are required. 
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MDefault) j 



^409 

^AUribules 

QCLSID 

QVoiceData 

QVoiceDef 

— — ^ — 1 



"Mary 
"Mary 

"Default;Mary;Microsoft;LCID_409;Female;Normal" 
"{65DBDDEF-0725-1 1 d3-B50C-00C04F797396}" 
"d:\sapi5\src\tts\msttsdrv\voices\Mary.vData" 
"d:\sapi5\src\tts\m3ttsdrv\voices\Mary.vDef" 



An example of the Microsoft TTS engine registries are shown above: 
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Application design considerations 



The following section covers: 



• Using text to speech for short phrases 

• Presenting irnportmt information y 

• Avoiding a mix of text to speech and recorded voice 

• Making text to speech optional 
Using text to speech for short phrases 

An application should use text to speech only for reading short phrases or notifications, 
not long passages of text. Listening to a synthesized voice read more than a few 
sentences requires more concentration and a user can become distracted. 
Presenting important information visually 

An application should conmiunicate critical information visually as well as audibly, and 
it should not rely solely on text to speech to communicate important information. The 
user can miss spoken messages for a variety of reasons, such as not having speakers or 
headphones attached to the computer, being distracted, or being physically away from 
the computer when the application speaks. Or the user may have simply turned off text to 
speech. 

Avoiding a mix of text to speech and recorded voice 

The synthesized voice provided by even the best text-to-speech engine is noticeably 
different from that provided by a digital-audio recording. Mixing the two in the same 
utterance can be disturbing to the user and usually makes the text-to-speech voice sound 
worse by comparison. For example, to have an application speak "The number is 
56,738," the user should not prerecord "The number is" then use text to speech to speak 
the numbers. Everything should be either prerecorded or text to speech. 
Making text to speech optional 

Applications should enable the user to tum off the text-to-speech feature. Some users 
work in environments where audible speech or sound eminating from a computer could 
distract coworkers. Additionally, it may be undesirable to audibly share computer 
information v^th others in the work environment. 

Back to top 



Microsoft Speech SDK 
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with SAPI 5.0 



[This is preliminary docmneBtation and subject to change,] 



Text synthesis 



SAPI 5.0 utilizes the Extensible Markup Language (XML) to define text synthesis 
characteristics and application configuration settings. 

A text-to-speech (TTS) engine that uses synthesis generates sounds similar to those created by 
the human voice and applies various filters to simulate throat length, mouth cavity, lip shape, 
and tongue position. Although the voice produced through text synthesis often sounds less 
human §ian a voice produced by diphone concatenation, it is possible to obtain different 
qualities of voice throu^ modifymgTTS configuration settings. SAPI 5.0 compliant TTS 
engines can achieve improved synthesized text-to-speech voice qualities using XML to 
control the configuration settings for text synthesis. 

The following section covers: 

• Syntheses mark^^ 

• Scope of XML element 

• Context tag definition 



SAPI 5.0 synthesis markup is the collection of XML tags inserted into text to modify the 
speech synthesis of that text. These XML tags, which provide fimctionality such as volume 
control and word emphasis, are inserted into text passed into ISpVoice::Speak and text streams 
of format SPDFID_XML which are then passed into ISpVoice::SpeakStream. Please see 
ISpVoice for more information. 

SAPI 5.0 synthesis markup is an appUcation of XML. Every XML element consists of a start 
tag <Some_tag> and an end tag </Some_tag> with a case-sensitive tag name and contents 
between these tags. If the element is empty, it has no contents <SomeJag></SomeJag> and 
the start tag and the end tag might be the same <Some_tag/>. More information about XML 
and the XML specification is available at: http://www.w3.org/TR/1998/REC-xml- 
1 99802 10.html. 

The following section covers: 

• SAPI 5.0XMLtags 

• Attributes 

• Contents 

• Comments 

• Relationship to HTML web pages and SABLE 



© 1995:2000 Microsoft C^^ reserved. 
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Synthesis markup 



SAPI 5.0 XML tags 
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SAPI 5.0 XML tags 

XML tags in SAPI 5.0 follow a defined structure program scope and implementation. SAPI 5.0 
XML tags have a specific purpose and affect the input text in a predetermined manner. 

The SAPI 5.0 XML tags are divided into four different scope categories. 

1. Non-scoped 

2. Scoped 

3. Global 

4. Scoped/Global 

The behavior and application-specific properties can be controlled through the use of XML 
tags. Additional information on SAPI 5.0 XML elements is available at: Scope of XML 
elements . 

Attributes 

Attributes of an XML element appear inside the start tag. Each attribute is in the form of 
a name, followed by an equal character, followed by a quoted string value. An attribute 
of a given name may only appear once in a start tag. Exact details on what characters 
may appear between quotes can be found at http://www.w3 .org/TR/REC-xml#NT- 
AttValue. 

Briefly, the literal string cannot contain a less than character "<" if the string is 
surrounded by single quotation marks, it cannot contain a single quotation mark. If the 
string is surrounded by double quotation marks it cannot contain a double quotation 
mark. Furthermore, all ampersands (&) can be used only in an entity reference such as 
& and ">". When a literal string is parsed, the resuhing replacement text will 
resolve all entity references such as ">" into its corresponding text, such as 

In this specification, only the resulting replacement text needs to be defined for attribute 
value strings. The XML specification defines the exact file syntax details. Character 
references allow entity references in ASCII characters to specify replacement text which 
has unprintable characters such as extended UNICODE characters. The entity reference 
"ə" specifies the single UNICODE character for the International Phonetic 
Alphabet symbol for a mid-central unroimded vowel. See 
http://www.w3,org/TR/1998/REC-xml-19980210#sec-references for details. 

Contents 

The contents of an element consist of text or sub-elements. With these definitions, the 
XML specification defines the exact file syntax details. 
Comments 

Comments of the form <!-- my comment ~> are supported. More information about 
comments and the XML specification is available at: http://www.w3.org/TR/REC- 
xml#sec-comments. 

Relationship to HTML web pages and SABLE 

The XML format that SAPI 5.0 uses is NOT placed inside web pages. Web page authors who 
want to mark up sections of HTML text so that it is synthesized correctly, should use the W3C 
Aural Cascading Style Sheets (ACSS). More information is available at: 
http://www.w3 .org/TR/WD-acss 
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SAPI applications that are synthesizing text from a web page will "render" HTML+ACSS into 
SAPI's synthesis markup format. Programs apply a default ACSS file when synthesizing web 
pages that do not have an associated ACSS file. 

SAPI 5.0 synthesis markup format is similar to the format published by the SABLE 
Consortium. However, this format and SABLE version 1.0 are not interoperable. At this time, 
if s not determined if they will become partially interoperable in the future. More information 
about the SABLE specification is available at: http://www.bell-labs.com/project/tts/sable.htmL 

A Back to top 



SAPI Synthesis markup XML elements (tags) fall into one of four scope categories: 

1 . Non-scoped - an element which must be empty and does not directly affect the synthesis 
of input text around it. 

Valid tag formats are: <TAG/> 

2. Scoped - an element that contains input text, possibly zero-length, and only directly 
affects the input text that it contains. If this element is empty, it only directly affects the 
zero-length string it contains. 

Valid tag formats are: <TAG>,<TAG/> 

3. Global - an element which is empty and directly affects the rest of the input text 
following it in the input stream. 

Valid tag formats are: <TAG/> 

4. Scoped/Global - an element that can be used in either a scoped or global manner. 
VaUd tag formats are: <TAG/>,<TAG>,</TAG> 

The following table describes the synthesis markup elements/tags which are functional across 
all SAPI compliant synthesis engines: 

Element Scope Attributes Description 

BOOKMARK Non-scoped MARK Inserts a bookmark. 



P. ) 995-2000 Microsoft CprBoration. AH ri ghts reserved. 
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Scope of XML elements 



EMPH 
SPELL 
PRON 



SILENCE 



non-scoped MSEC 



Scoped None 
Scoped None 
Scoped/Non- SYM 



Inserts silence for a specified number of 
milliseconds. 

Places emphasis on words. 
Spells out words letter by letter. 
Pronounces according to International 
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scoped 


C A T>T 


oCOpcQ IN one 


T ANn 


Sconed/Global LANGID 


r /\lv 1 \Jr or_ 


Cponpfl PART 


VOICE 


Scopea/Cjlobal Kbi^ulKbJJ, 




OPTIONAL 


T> ATF 
JxAl lt( 






ABSSPEED 


VOLUME 


Scoped/Global LEVEL 


PITCH 


Scoped/Global MIDDLE, 




ABSMIDDLE 


CONTEXT 


Scoped Type 



Phonetic Alphabet. 

Indicates to the XML parser that the XML 

tags contained within the scope should be 

parsed as SAPI tags. 

Language/locale of contained text. 

Part of speech of contained word(s). 

Sets which voice implementation is used for 

synthesis. 

Sets the relative adjustment for speaking 

speed of synthesized speech. 

Sets the volume of synthesized output. 

Sets the relative pitch adjustment of 

synthesized speech. 

Context of the text that is being parsed. 



Guaranteed XML Elements 



BOOKMARK ^. . 

Inserts a bookmark into the input stream using the bookmark element. If an application 
specifies interest in bookmark events, it will receive an event when synthesis has passed 
this element in an input stream. If the audio output destination supports handling of 
events, then an application will receive this event once the synthesized speech up to this 
bookmark has been output. Otherwise, an application receives a bookmark event when 
the voice implementation has synthesized speech up to this bookmark. 



MARK 

The value of a bookmark may be any string or integer. 



^ Back to top 



SILENCE 

Produces silence for a specified number of miUiseconds to the output audio stream. 



Number of milliseconds, from zero to 65535, of silence. Value entries that exceed this 
range should be hmited to 65535. Value entries that are below this range (negative 
values) should be set to zero. 



Back to top 



EMPH 

Places emphasis on the words contained by this element. 



A Back to top 



SPELL 

Spells out words letter by letter contained by this element. 

Note: The engine should not normalize the text scoped in the SPELL tag. This includes 
numbers, words, etc. Words that contain punctuation, such as "U.S.A." should spell out 
the letters as well as the punctuation scoped within the tag. 



^ Back to top 
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PRON . ^ 

Pronounces the contained text (possibly empty) according to the provided Unicode 

string. 

See American English Phoneme Representation for more information, 
SYM 

String representing a phoneme for a language supported by the voice implementmg 
synthesized speech. 

A Back to top 

SAPI ^ , 

At the beginning of the SAPI tag, the state of the voice is the same state as the msertion 
point of the SAPI tag. At the close of the SAPI tag, the voice returns to the same state as 
that of the insertion point. SAPI tags may be nested. When a nested SAPI tag is closed, 
the voice state retums to what it was at the insertion point of the nested tag. 

-K Back to top 

^^^^hanges the LANGID of the scoped text. When the LANGID is changed, SAPI will try 
to detect if the current voice can handle the new language. 

If voice does not speak the specified language, then an engine must choose another 
language it speaks as a best attempt. Using the VOICE tag and REQUIRED attribute, 
this fall back path can be prevented if not desirable. 

LANGID 

Language identifier. 
Back to top 

PARTOFSP ^ ^ 

The part of speech of contained word(s). The PARTOFSP tag is used to force a 
particular pronunciation of a word (for example, the word record as a noun versus the 
word record as a verb). 

PART 

String name of part of speech. Following are valid parts of speech: 

• noun 

• verb 

• modifier 

• function 

• interjection 

• abbreviation 

• xmknown 

^ Back to top 
VOICE 

Sets which voice implementation is used for synthesis of associated input stream text. 11 
the user specifies a voice ID, then a specific voice implementation will be selected, 
otherwise the best voice implementation given the required and optional attributes will 
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be selected by SAPL 
ID 

The progID (class ID) of a component supporting the ISpTTSEngme interface that 
provides a voice implementation. This attribute takes precedence over the 
REQUIRED/OPTIONAL attributes if used together. If the specific voice progID is not 
found on the system, the XML parser will do a best match based on the 
REQUIRED/OPTIONAL attributes. If these attributes are not specified, the XML parser 
uses the default voice. 

REQUIRED 

The XML parser selects the first voice registered containing all of the specified 
attributes. A string that contains semicolon-delimited sub-strings is used to specify the 
attributes. The speak call ^n\\\ fail if the parser cannot find the required tags. 

The following are required attributes: 

• name 

• age group 

• vendor 

• language 

• gender 

• CLSID 

OPTIONAL 

The XML parser selects the first voice registered containing all of the REQUIRED 
attributes, and has the best match to the specified OPTIONAL attributes. Optional 
attribute importance is specified by the order that they appear in the string. The first sub- 
string is the most important. A string that contains semicolon- Vdelimited sub-strings is 
used to specify the optional attributes. 

The optional attributes are: 

• name 

• age group 

• vendor 

• language 

• gender 

• CLSID 

• description 

Backto top 

VOLUME, PITCH, RATE 

The scoped/global elements, VOLUME, RATE and PITCH respectively, modify the 
underlying numerical values of a speech block. Relative attribute values, those preceded 
by a dash (-) or a plus sign (+), increment the underlying numerical value by the 
specified amount. 

For VOLUME, the underlying value can never be below zero or exceed 100. AH 
negative value entries will result in zero and all values above 100 will result in 100. 
VOLUME may also receive an absolute value (no '-' or '+' character) of an integer 
between zero and 100. For PITCH and RATE, SAPI compliant engines have the option 
of supporting only the guaranteed range of values and behaving as -10 for adjustments 
below -10 and behaving as +10 for values above +10. 
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Element 


Attribute 


Valid 
Strings 


Guaranteed Range 


VOLUME 


LEVEL 


"N" 


0 to 100 (no overflow allowed) 


rllUrl 


\>fTrir>T V 

NliLflJLti^ 


"IN Ul 


-1 0 to 10 ^nverflow allowed^ 


RATE 


SPEED 


^'-N" or 


(overflow allowed) 



X Back to top 

VOLUME 

Set the volume of synthesized output. 

LEVEL , . 

Specifies the volume as percent of the maximum volume of the current voice. Each voice 
implementation has its own maximum volume. This value must be between zero and 100 
inclusive. 

x Back to top 

PITCH 

Sets the relative pitch adjustment of synthesized speech. 

MIDDLE , . . ^ , 

The value can range from -10 to +10. A value of zero sets a voice to speak at its detauit 
pitch. A value of -10 sets a voice to speak at three fourths (or 3/4) of its default pitch. A 
value of +10 sets a voice to speak at four tWrds (or 4/3) of its default pitch. Each 
increment between -10 and +10 is logarithmically distributed such that 
incrementing/decrementing by one is multiplying/dividing the pitch by the 24th root of 
two (about 1.03). Values more extreme than -10 and +10 will be passed to an engine, but 
SAPI 5.0 compliant engines may not support such extremes and instead may clip the 
pitch to the maximum or minimum pitch it supports. Values of -24 and +24 must lower 
and raise pitch by one octave respectively. All uicrementing/decrementing by one must 
multiply/divide the pitch by the 24th root of two. When scoped, this attribute is relative. 

The following is an example of the <PITCH> tag and the MIDDLE attribute. 

<SAPI>Pitch adjustment zero, 

<PITCH MIDDLE="-3">pitch adjustment -3, 

<PITCH MIDDLE=" -3">pitch adjustment -6,</PITCH> 
back to adjustment -3, 
</PITCH> 

and back to adjustment zero, the default pitch. 

</SAPI> 

ABSMIDDLE 

The value can range from -10 to +10. A value of zero sets a voice to speak at its defauh 
pitch. A value of -10 sets a voice to speak at three-fourths (or 3/4) of its default pitch. A 
value of +10 sets a voice to speak at four-thirds (or 4/3) of its default pitch. Each 
increment between -10 and +10 is logarithmically distributed such that 
mcrementing/decrementing by one is multiplying/dividing the pitch by the 24th root of 
two (about 1.03). Values more extreme than -10 and 10 will be passed to an engine but 
compliant engines may not support such extremes and instead may clip the pitch to the 
maximum or minimum pitch it supports. Values of -24 and +2SAPI 54 must lower and 
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maximum or minimum pitch it supports. Values of -24 and +2SAPI 54 must lower and 
raise pitch by one octave respectively. All incrementing/decrementing by one must 
multiply/divide the pitch by the 24th root of two. When scoped, this attribute is absolute. 

The following is an example of the <PITCH> tag and the ABSMIDDLE attribute. 

<SAPI>Pitch adjustment zero, 

<PITCH ABSMIDDLE="-3">pitch adjustment -3, 

<PITCH ABSMIDDLE ="-3">pitch adjustment -3, 

</PITCH> 
back to adjustment -3, 
</PITCH> 

and back to adjustment zero, the default pitch. 
</SAPI> 

Back to top 

RATE , . ^ 

Sets the relative speed adjustment at which words are synthesized. 

SPEED . , . J ^ u 

The value can range from -10 to +10. A value of zero sets a voice to speak at its deiault 
rate. A value of -10 sets a voice to speak at one-third of its default rate. A value of +10 
sets a voice to speak at three times its default rate. Each increment between -10 and +10 
is logarithmically distributed such that incrementing/decrementing by one is 
multiplying/dividing the rate by the tenth root of three (about 1.12). Values more 
extreme than -10 and +10 will be passed to an engine but SAPI 5.0 comphant engines 
may not support such extremes and instead may clip the rate to the maximum or 
minimum rate it supports. 

The following is an example of the <RATE> tag and the SPEED attribute: 

<SAPI>Rate adjustment zero, 

<RATE SPEED="-3">rate adjustment -3, 

<RATE SPEED="-4">rate adjustment -7, 

</RATE> 
back to adjustment -3, 
</RATE> 

and back to adjustment zero, the default rate. 
</SAPI> 

ABSSPEED . 1 . J ^ u 

The value can range from -10 to +10. A value of zero sets a voice to speak at its detault 
rate. A value of -10 sets a voice to speak at one-third (or 1/3) of its default rate. A value 
of +10 sets a voice to speak at three times its default rate. Each increment between -10 
and +10 is logarithmically distributed such that incrementing/decrementing by one is 
multiplying/dividing the rate by the 10th root of three (about 1.12). Values more extreme 
than -10 and +10 will be passed to an engine, but SAPI 5.0 comphant engines may not 
support such extremes and instead may clip the rate to the maximum or minimum rate it 
supports. When scoped, this attribute is absolute. 

The following is an example of the <RATE> tag and the ABSSPEED attribute: 

<SAPI>Rate adjustment zero, 

<RATE ABSSPEED="-3">rate adjustment -3, 

<RATE ABSSPEED="-4">rate adjustment -4, 

</RATE> 
back to adjustment -3, 
</RATE> 
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and back to adjustment zero, the default rate. 
</SAPI> 

A Back to top 

CONTEXT ^ ^ ^ ^^^^ 

Context specifies the type of normalization rules which to apply to the scoped text. SAFl 
does not guarantee any predefined contexts. For additional information, please see 
Context tag defimtion. 

ID 

This specifies the type of context. 
SAPI predefined context IDs 

Context type 

date_mdy 

date_dmy 

date_ymd 
Date date^j^"^ 
^^^^ date__my 

date_dm 

datemd 

date_year 

Time time 

number_cardinal 
, nvimber digit 
numberlfrJction 
number_decimal 

Phone_Number phone__number 

Currency currency 

\\7 u web_url 
web email 



Postal 

A Back to top 



postal 

address_postal 



) 1995-2000 Microsoft CorporatLon. AH risl?ts_ reserved. 
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Context tag definition 

The CONTEXT tag specifies the normalization of a block of text. This specification defines the 
SAPI predefined attributes (ID) for the CONTEXT tag. These IDs are strings. SAPI does not 
perform any parameter validation on the string passed to the engine, hence, the application can 
specify engine-specific normalization IDs to the engine. Engine-specific strings should begin 
with the engine vendor's name to avoid confusion between engines. 

For example: 

<CONTEXT ID = "MS_My_Context"> text </CONTEXT> 

The exact implementation of some of these values is dependent on the engine in SAPI 5. In 
order to force a certain normalization, the application developer may choose to use another 
SAPI tag, an engine specific ID, or normalize the text themselves. Each context tag may 
contain more than one string. 

For example: 

<CONTEXT ID = "date_mdy"> 12/21/99 11/21/99 10/21/99 </CONTEX'I> 

would be normalized to "December twenty first nineteen ninety nine November twenty first 

nineteen ninety nine October twenty first nineteen ninety nine." 

Note: In SAPI 5.0 the exact implementation of some of these values depends on the engine. In 
order to force a certain normalization, the application developer may choose to use another 
SAPI tag or an engine specific ID. The developer may choose to normalize the text. 

The following predefined context types are covered in this section: 

• Date 

• Time 

• Number 

• PhoneNumber 

• Currency 

• Web ' 

• E-mail 

• Address 

Date 

This context specifies that the number passed to the engine is a date. Dates will generally have 
the format of number [delimiter] number [delimiter] number or number [delimiter] number 
where the delimiter may be a T or and numbers are typically between 01 and 12 for 
months, 01 and 31 for days. A year is generally a two or four digit number. 
The following are valid string types: 



This will normalize the date such that the first group of numbers is the month, the second 
group is the day, and the third group is the year. In the case where the year is a two digit 
number, the engine may read it as a two digit number or a four digit number. 

For example: 
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<context ID = "date_mdy">12/21/99</context> 

will be normalized to "December twenty first ninety nine" 

or "December twenty first nineteen ninety nine" 

<context ID = "date_mdy">12/21/1999</context> 

will be normalized to "December twenty first nineteen ninety nine" 

Back to top 

date_dmy 

This will normalize the date such that the first group of numbers is the day, the second 
group is the month, and the third group is the year. In the case where the year is a two 
digit number, the engine should read it as a two digit number. If the year is represented 
as a four digit number, it will be represented as a four digit year. 

For example: 

<context ID = "date_dmy">21.12.99</context> 

will be normalized to "December twenty first ninety nine" 

or "December twenty first nineteen ninety nine" 

<context ID = "date_ dmy">21-12-1999</context> 

will be normalized to "December twenty first nineteen ninety nine" 

5s: Back to top 

datej^md 

This will normalize the date such that the first group of numbers is the year, the second 
group is the month, and the third group is the day. In the case where the year is a two 
digit number, the engine should read it as a two digit number. If the year is represented 
as a four digit number, it will be represented as a four digit year. 

For example: 

<context ID = "date_ymd">99-12-21</context> 

will be normalized to "December twenty first ninety nine" 

or "December twenty first nineteen ninety nine" 

<context ID = "date_ ymd">1999.12.21</context> 

will be normalized to "December twenty first nineteen ninety nine" 

jZ Back to top 

date_jm 

This will normalize the date such that the first group of numbers is the year, and the 
second group is the month. In the case where the year is a two digit number, the engine 
should read it as a two digit number. If the year is represented as a four digit number, it 
will be represented as a four digit year. 

For example: 

<context ID = "date_ym">99-12</context> 
will be normalized to "December ninety nine" 
or "December nineteen ninety nine" 
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<context ID = "date_ ym">1999.12</context> 

will be normalized to "December nineteen ninety nine" 

a: Back to top 

date_my 

This will normalize the date such that the first group of numbers is the month, and the 
second group is the year. In the case where the year is a two digit nxmiber, the engine 
should read it as a two digit number. If the year is represented as a four digit mmiber, it 
will be represented as a four digit year. 

For example: 

<context ID = "date_my">12/99</context> 
will be normalized to "December ninety nine" 
or "December nineteen ninety nine" 

<context ID = "date_my">12/1999</context> 

will be normalized to "December nineteen ninety nine" 

^ Back to top 

date_dm 

This will normalize the date such that the first group of numbers is the day and the 
second group is the month. 

For example: 

<context ID = "date__dm">2L12</context> 
will be normalized to "December twenty first" 

'K Back to top 

date md i j t. 

This will normalize the date such that the first group of numbers is the month and the 

second group is the day. 
For example: 

<context ID = "date_md">12/21</context> 
will be normalized to "December twenty first" 

^ Back to top 
date_year 

This will normalize the date such that the number is read as a year. 
For example: 

<context ID = "date_year">1999</context> 
will be normalized to "nineteen ninety nine" 
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<context ID = "date_year">2001</context> 
will be normalized to "Two thousand one" 

Back to top 

Time 

This context specifies that the number passed to the engine is a time. Times will generally have 
the format of number [delimiter] number [delimiter] number or number [delimiter] number 
where the delimiter is ':' or " ' or ' " ' and numbers are typically between 01 and 24 for hours, 
01 and 59 for minutes and seconds. 

When a zero is present in numbers between 01 and 09, the engine may choose to ignore this, or 
normalize it as "oh". The engine may also choose to place an "and" in the normalized time. The 
valid string types are: 

For example: 

<context ID = "time">12:30</context> 
will be normalized to "twelve thirty" 

<context ID - "time">01:21</context> 
may be normaUzed as "one twenty one" 
or "oh one twenty one" 

<context ID = "time">l '2 1 "</context> 

may be normalized as "one minute twenty one seconds" 

or "one minute and twenty one seconds" 

Back to top 

Number 

number_cardinal r ^ . 

The text should be normalized as a number using the regular format ot ones, tens, etc. 
The engine may choose to place "and" in the normalized text. 

For example: 

<context ID = "number_cardinal">3432</context> 

will be normalized to "three thousand four hundred thirty two" 

<context ID = "number_cardinal">3432</context> 

will be normalized to "three thousand four hundred and thirty two" 

^ B ack to top 

number_digit 

The text should be normalized digit by digit. 

For example: 
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<context ID = "number_digit">3432</context> 
will be normalized to "three four three two" 



Back to top 



number_fraction 

The text should be normalized as a fraction. 

For example: 

<context ID = "number_fraction">3/15</context> 

will be normalized to "three fifteenths" or "three over fifteen" 



Back to top 



numberdecimal 

The text should be normalized as a decimal value. 

For example: 

<context ID = "number_decimal">423.1243</context> 

will be normalized to "four hundred and twenty three point one two four three" 

X Back to top 

Phone Number . i . n 

The text should be normalized as a phone number. The exact implementation ot this will 
be left to the engine and maybe defined in a fixture release of SAPI. 



Back to top 



Currency 

The text should be normalized as a currency. The exact implementation of this will be 
left to the engine and maybe defined in a future release of SAPI. 

For example: 

<context ID = "currency">$34.90</context> 

will be normalized to "thirty four dollars and ninety cents" 

Backto top 

Web 

The text should be normalized as a url. The exact implementation of this will be left to the 
engine and maybe defined in a future release of SAPI. 

web_url 

For example: 

<context ID = "web url">www.Microsoft.com</context> 
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will be normalized to "may be normalized to "w w w dot Microsoft dot com" 
^ Back to top 
E-mail 

The text should be normalized as e-mail. The exact implementation of this will be left to the 
engine and maybe defined in a fixture release of SAPI. 

E-mail_address 

The text should be normalized as an e-mail address. The exact implementation ot this 
will be left to the engine and maybe defined in a future release of SAPI. 

For example: 

<context ID = "E-maiLAddress">someone@microsoft.com</context> 
may be normalized to "Someone at Microsoft dot com" 

-K Back to top 

Address 

The text should be normalized as an address. The exact implementation of this will be 
left to the engine and maybe defined in a future release of S APT 

For example: 

<context ID - "address">One Microsoft Way, Redmond, WA, 98052</context> 
will be normalized to "One Microsoft Way Redmond Washington nine eight zero five 
two" 

address postal . x-^i.- *n 

The text should be normahzed as a postal address. The exact implementation ot this will 
be left to the engine and maybe defined in a fixture release of SAPI. 

For example: 

<context ID = "address jostal">A2C 4X5</context> 
will be normalized to "A 2 C 4 X 5" 

^ Back to top 

© 1995-2000 Microsoft Corporation Mi rights reserved . 

Microsoft Speech SDK 

with SAPI 5.0 . O 



[This is preliminary documentation and subject to change, 

ISpVoice 
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The ISpVoice interface enables an application to perform text synthesis operations. 
When to Use 

An application uses the ISpVoice interface to communicate with a SAPI-compliant TTS 
engine. The ISpVoicexSpeak method creates a synthesized output using the engine. It is 
possible for an application to speak text files or mix synthesized text with audio files m 
addition to text streams. An appUcation can do this by speaking synchronously or 
asynchronously. 

Applications can choose a specific TTS voice using the _ISpVoice::Setyoice. In order to change 
the state of the voice (for example, rate, pitch, and volume), use XML inside the ::speak call. 
Voices can receive different priorities usmg the ISpVoice: :SetPnMtY- This allows voices with 
a higher priority to interrupt a voice with a lower priority. 

SAPI retums synthesis events to the application mforming the application that the engine has 
processed a certain event such as bookmarks or phonemes. 

ISpVoice inherits from the ISpEyentSqurce interface. 

Methods in Viable Order 

ISpVoice Methods 
Setputput 

GetOutputObjectTpken 
GetOutputStream 
Pause 
Resume 

SetVoice 
GetVoice 
Speak 

SpeakStream 
GetStatus 

Skip 

SetPriority 
GetPriority 
SetAlertBoundary 

GetAlertBoundary 

SetRate 
GetRate 



Description 

Sets the current output destination. 

Retrieves the current output stream object token. 

Retrieves a pointer to an output stream. 

Pauses the voice and closes the output device. 

Sets the output device to the RUN state and resumes 

rendering. 

Sets the identity of a voice used in text synthesis. 
Retrieves the engine voice token information. 
Enables the engine to speak the contents of a speak a 
text bxrffer. 

Enables the engine to speak the contents of a stream. 

Retrieves the current rendering and event status 
associated with this voice. 

Enables the engine to skip ahead the specified number 
of items within the current speak request. 

Sets the queue priority for a voice. 
Retrieves the current voice priority level. 
Specifies which event should be used as the insertion 
point for alerts. 

Retrieves which event should be used as the insertion 
point for alerts. 

Sets the engine's rate of spoken text. 
Retrieves the engine's rate of spoken text. 
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SetVolume 
GetVolume 
WaitUntilDone 



GetSyncSpeakTimeout 



SetSyncSpeakTimeout 



SpeakCompleteEvent 



IsUISupported 
DisplayUI 



Sets the output volume leveL 

Retrieves the current output volume level 

Specifies the time interval to wait for the speech queue 

to complete processing. 

Sets the timeout interval for synchronous speech 
operations. 

Retrieves the timeout interval for synchronous speech 
operations. 

Returns an event handle used to wait until the voice 
has completed speaking. 

Determines if the specified type of UI is supported. 
Displays the requested UL 



© 1995-2000 Microsoft Corppratjpn.„M^ reserved 



[This is preliminary documentalion and subject to change.] 




ISpVoice::SetOutput 



ISpVoice::SetOutput sets the current output destination. Output may be in the form of audio 
or text. 

SetOutput ( 

lUnknown *pUnkOutputr 

BOOL fAl 1 owForma tChanges 

); 

Parameters 

pUnkOutput , 

[in] Address of an lUnknqwn interface containing the output stream destination 

information. 
fAllowFormatChanges 

[in] Flag specifying whether the stream is set to allow format changes. 

Return values 

Value Description 

S OK Function completed successfully. 

E^INVALIDARG One or more arguments are invalid. 

E__POINTER Invalid pointer. 

E OUTOFMEMORY Exceeded available memory. 



© 1995^2000 Microsoft CorpomiLon Aljjighfe reserved 



[rhis is preliminar}^ documentation and subject to change. | 
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ISp Voice: :GetOutputObjectToken 

ISpVoice::GetOutputObjectToken retrieves the current output stream object token. 

HRESULT GetOutputOb j ectToken ( 

ISpObjectToken **ppObj ectToken 

); 

Parameters 

ppObjectToken . 

[out] Address of the ISpObjectToken that receives the output stream object token. 

Return values 

Value Description 

S OK Function completed successMly. 

E INVALIDARG One or more arguments are invalid. 

FAILED (hr) Appropriate error message. 

© 1 995-2000_Micrpsoft Corporation. AlLrights_reser\'ed 



[This is preliminaiy documentation and subject to change.] W 

ISpVoice: -.GetOutputStream 

ISpVoice::GetOutputStream retrieves a pointer to an output stream. 

HRESULT GetOutputStream ( 

ISpS treartiFormat * ^ppStream 

); 

Parameters 

ppStream . 

[out] Address of a pointer to an ISpStreamFormat that receives the output stream. 

Return values 

Value Description 

S OK Function completed successfully. 

E^INVALIDARG One or more arguments are invalid. 

FAILED (hr) Appropriate error message. 

©J 995-_200p Microsoft Corporation, All_rights reserved 
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[This is preliminary documentation and subject to change.] 




ISp Voice: :Pause 



ISp Voice: rPause pauses the voice and closes the output device. 

HRESULT Pause { void ) ; 

Parameters 

None. 

Return values 

Value Description 

S OK Fxmction completed successfully. 

FAILED(hr) Appropriate error message. 



ISp Voice: :Resume sets the output device to the RUN state and resumes rendering. 

HRESULT Resiime ( void ) ; 

Parameters 

None. 

Return values 

Value Description 

S OK Function completed successfully. 

FAILED (hr) Appropriate error message. 



©1995-2000 MLcrp_spft Corporatioii. AH rights reserved. 



This is preliminary documentation and Siibject to change.] 




ISp Voice: :Resume 



© l_995-2p00_ Microsoft Corporation.^ All rights resented 



[This is preliminary documentation and subject lo change.] 




ISp Voice : : SetVoice 
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ISpVoice::SetVoice sets the identity of a voice used in text synthesis. 

HRESULT SetVoice( 

ISpObjectToken *pToken 

); 

Parameters 

^^^^^ [in] Address of the ISpObjectToken interface containing the voice implementation to be 
used in the synthesis operation for this ISpVoice instance. The system default voice is 
selected if tiiis pointer is NULL. 

Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG One or more arguments are invalid. 

E POINTER Invalid pointer. 

Remarks 

• Changing the voice selection v^iW preserve the same volume and rate levels for a voice. 

• If the SetVoice method is not called, the first call into the ISpVqice interface requiring a 
voice implementation will initialize it. This results in the default voice for the system to 
be chosen and initialized for this ISpVoice instance. 

©i?95-2MlMicrosoft Corporation. All_rig.hts resented. 



[This is preliminaiy documentation and subject to change.] 

ISpVoice: :GetVoice 

ISpVoice::GetVoice retrieves the voice identity used in text synthesis. 

HRESULT GetVoice( 

ISpObj ec tToken * *ppToken 

); 

Parameters 

ppToken . ^ 1 • J 

[out] Address of a pointer to the ISpObjectToken object representing the synthesized 
voice implementation used for this ISpVoice instance. 

Return values 

Value Description 

S OK Function completed successfully. 
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E^INVALIDARG One or more arguments are invalid. 

E POINTER Invalid pointer. 



Note: 



If there is an error in the initialization of GetVoice, the error returned will not occur until 
Speak or SpeakStream methods are called. 



© 1995-20Q0 Microsoft Corporation All rights reserved 



[This is preliminary^ documentation and subject to change] ^0 

ISpVoice:: Speak 

ISpVoice::Speak enables the engine to speak the contents of a stream. 
This stream may be a text file, text buffer, wav file or other streaming source. 

HRESULT Speak ( 

const WCHAR *pwcs, 

DWORD dwFlags, 

ULONG *pulStreainNumber 

); 

Parameters 

[in, string] Address of a buffer null-terminated text strmg contammg the synthesis 
markup to be synthesized. This value can be NULL when dwFlags is set to 
SPF_PURGEBEFORESPEAK indicating that the audio data currently being sent to the 
audio destination is to be purged and the synthesis process stopped. 

dwFlags . 1 • t. 

[in] Value indicating the attributes of the text stream. These values are contamed m the 

SPEAKFLAGS enumeration. 
pulStreamNumber . . t i.* 

[out] Address of a value specifying the current input stream number associated with this 

Speak instance. 
Return values 

Value Description 

S OK Function completed successfully. 

E_INVALIDARG One or more arguments are invalid. 

E^POINTER Invalid pointer. 

E^OUTOFMEMORY Exceeded available memory. 

SPERR_INVALID_FLAGS InvaHd flags specified for this operation. 

SPERR_DEVICE_BUSY Timeout occurred on synchronous call. 

Remarks 
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• The first call into ISpVoice::Speak or ISpyoice::Sp_eakStreain for an ISpVpice instance 
will be assigned a stream number of zero. Every subsequent call to Speak and 
SpeakStream is assigned one plus the stream number of the previous call to either Speak 
or SpeakStream (relative to the ISpVoice instance, not the calling thread). 

• If there is an error in the initialization of ISpVoice: :GetVoice, the error returned will not 
occur until ISj)Voice::Speak or ISpVoice::SpeakStre_am metiiods are called. 



© 1_995-200P Microsoft Corporation .Mrightsjese^^ 



[This is preliminary documentation and subject to change.] ^ 

ISpVoice: -.SpeakStream 

ISpVoice:: SpeakStream enables the engine to speak the contents of a stream. 

HRESULT Speaks tr earn { 
IS t ream *pStream , 
DWORD dwFlags, 
ULONG *pulStreamNumber 

); 

Parameters 

pStream t^> i to o 7- 

[in] Address of an IStream interface containing the input stream. If the ISpStreamt prmat 
interface is not supported the input stream format type is specified as SPFID_Text, 

<ivMF/ag^^ Value indicating the attributes of the text stream. These values are contained in the 

SPEAKFLAGS enumeration. 
pulStreamNumber • j - u 

[out] Address of a variable that receives the current input stream number associated with 

this SpeakStream instance. 

Return values 



Value 

S_OK 

E_INVALIDARG 
E_POINTER 
E_OUTOFMEMORY 
SPERR_INVALID„FLAGS 
SPERR DEVICE BUSY 



Description 

Function completed successfully. 

One or more arguments are invalid. 

Invalid pointer. 

Exceeded available memory. 

Invalid flags specified for this operation. 

Timeout on synchronous call. 



Remarks 

• If the input stream is wav data, it is sent directly to the destination stream. 

• If the input stream is text data, it is processed by the text-to-speech (TTS) engine. 

• The first call into Speak or SpeakStream for an ISpVoice instance will be assigned a 
stream number of zero. Every subsequent call to Speak and SpeakStream is assigned one 
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stream number of zero. Every subsequent call to Speak and SpeakStream is assigned one 
plus the stream number of the previous call to either Speak or SpeakStream (relative to 
the ISpVoice instance, not the calling thread). 

©J995:20p0 MicrosLOft Cp^ All.rights re_seryed. 



[This is preliminary documentation and subject to change.] 

ISpVoice: :GetStatus 

ISpVoice: :GetStatus retrieves the current rendering and event status associated with this 
ISpVoice instance. 

HRESULT GetStatus( 

SPVQICESTATUS *pStatus, 
WCHAR * *ppszLastBookmark 

); 

Parameters 

pStatus ^ . ^ . 

[out] Address of a SPVQICESTATUS structure receiving the status information. 
Optionally, this can be NULL if the caller does not want this information. 

ppszLastBookmark . „ . • 

[out, string] Address of a pointer to a CoTaskMemAUoc allocated nuU-termmated stnng 
containing the last bookmark reached. If there are no last bookmarks, then a NULL will 
returned. Applications implementing this method must call CoTaskMemFreeQ to free 
memory associated with this string. Optionally, this value can be NULL if this retum 
value is not needed. 

Return values 

Value 

S_OK 

EJNVALIDARG 
E_POINTER 
E_OUTOFMEMORY 

© 199>2000_Microsoft Corporation AIl_ rights reserved 




Description 

Function completed successfully. 
One or more arguments are invalid. 
Invalid pointer. 
Exceeded available memory. 



■ \ 

[This is preliminar}' documentation and subject to change.] ^ 



ISpVoice:: Skip 



ISpVoice: :Skip enables the engine to skip ahead the specified number of items within the 
current speak request. 



HRESULT Skip( 

WCHAR *pIteittType, 
long INvmltems, 
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long 



INuml terns, 



ULONG *pulNuinSkipped 
); 

Parameters 

pItemType 

[in,string] Specifies the skipped speak request item type. 
INumltems 

[in] Specifies the number of items to skip in the current speak request, 
pulNumSkipped 

[out] The actual number of items skipped. 

Return values 

Value Description 

S OK Function completed successfully. 

E_INVALIDARG pItemType is invalid or bad. 

FAILED (hr) Appropriate error message. 



ISpVoice::SetOutput sets the queue priority for a voice. 

HRESULT SetPriorityC 

SPVPRIORITY ePriori ty 

); 

Parameters 

ePriority 

[in] Queue priority of type SPVPRIORITY associated with the current voice. 
Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG One or more arguments are invalid. 



• The alert priority voice will interrupt a normal priority voice. 

• When two alert priority voices are specified, the first voice will finish before the second 
voice will proceed. 

• SPVPRI_OVER is supported only on Windows 2000. 



© 1 995-2000 Microsoft Cqo>oratlQn. AIUlgKts reserved. 



[I^his is preliminary' documentation and subject to change. J 




ISp Voice: rSetPriority 



Remarks 
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[This is preliminary docimientation and subject to change.] ^B' 

ISp Voice: :GetPriority 

ISpVoice::GetPriority retrieves the current voice priority level, 

HRESULT GetPriority( 

SPVPRIORITY -^pePriori ty 

); 

Parameters 

pePriority 

[out] Priority information of type SPVPRIORITY. 
Return values 

Value Description 

S OK Function completed successfully. 

E_POINTER Invalid pointer. 

© 199 5- 200 0 Microsoft Cprpoxatjpn, Ail rights reserved 



[This is preliminar}^ documentation and subject to change] W 

ISp Voice: : SetAlertBoundary 

ISpVoice::SetAlertBoundary specifies which event should be used as the insertion point for 
alerts. 

HRESULT SetAlertBoundary ( 

SPSVENTENXJM eBoundary 

); 

Parameters 

eBoundary ^ , ^ ^ , , ^ ^ r 

[in] Address of a SPEVENTENUM enumeration that specifies which event to use for the 

alert insertion point information. 
Return values 

Value Description 
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S_OK Function completed successfully. 

E_INVALIDARG One or more argimients are invalid. 

FAILED (hr) Appropriate error message. 



© 1995-2000 Microsoft Corporatipn,_AlJ ri^ts reserved. 



[This is preliminary documentation and subject to change.] 

ISp Voice: :GetAlertBoundary 

ISpVoice::GetAlertBoundary retrieves which event to be used as the uisertion point for 
alerts. 

HRESULT GetAlertBoundary ( 

SPEVENTENUM *peBounda3ry 

); 

Parameters 

peBoundary . ^ . 

[out] Address of a SPEVENTENUM enumeration that receives the event information 
specifying the alert insertion point information. 

Return values 

Value Description 

S OK Function completed successfully. 

E_POINTER Invalid pointer. 

FAILED (hr) Appropriate error message. 

©. 1995:2000 Microso_ft„Con)oratipn_ AU rightsreserv'ed. 



[This is preliminary documentation and subject to change.] 

ISp Voice: :SetRate 

ISpVoice::SetRate sets the engine's rate of spoken text relative to the normal rate. 
See Engine Characteristics for a detailed explaination of rate adjustment. 

HRESULT SetRate{ 

long RateAdjust 

); 

Parameters 

RateAdjust 
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[in] Value specifying the spoken text units per minute rate. 
Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG One or more arguments are invalid. 

E NOTIMPL This functionality is not implemented. 

Remarks 

• Voices do not have the same default rate. 

• The granularity of the rate is engine dependent. 



©J?95-200p_ Microsoft Corporation, All rights jeserved. 



[This is preliinmar\= documentation and subject to chajige.] 

ISpVoice::GetRate 

ISpVoice::GetRate retrieves the engine's rate of spoken text relative to the normal rate. 
See Engine Characteristics for a detailed explanation of rate adjustment. 

HRESULT GetRateC 

long *pRateAdjust 

); 

Parameters 

pRateAdjust - ^ • r> 

[out] Address of the value that receives the relative spoken text rate mtormation. Range 
must be between -10 and 10, inclusive. 

Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG One or more arguments are invalid. 

E NOTIMPL This functionality is not implemented. 

©J 995-2000 Microsoft Corporation _Ay rights reserved. 

[This is preliminary documentation and subject to change.] iSP 

ISp Voice: : SetVolume 
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ISpVoice::SetVolume sets the output volume level of speech synthesized by an engine. 



See Engine Characteristics for a detailed explanation of volume adjustment. 

HRESULT SetVolxane{ 
USHORT us Volume 

); 

Parameters 

us Voltitfic 

[in] Value containing the volume level information. Volume levels are specified in 
percentage values ranging from 0 to 100 percent. 

Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG One or more arguments are invalid. 



Remarks 

• Volume is specified as a percentage of the maximum volume of the current voice. Each 
voice implementation has its own maximum volume. 

• The usVolume parameter must between 0 (SPMIN__VOLUME) and 100 
(SPMAX_VOLUME) inclusive. These values are contained in the SPyLIMITS 
enumeration sequence. 

© 1995-2000 Microsoft Corporation, All rights reserved. 



[This is preliminary documentation and subject to change,] 

ISp Voice: :GetVolume 

ISpVoice::GetVolume retrieves the current output volume level of speech synthesized by an 
engine. 

See Engine Characteristics for a detailed explanation of volume adjustment. 

HRESULT GetVolume{ 

USHORT *pusVolvme 

); 

Parameters 

vus VolufTic 

[out] Address of the value that receives the volume level information. Volume levels are 
specified in percentage values ranging from 0 to 100 percent. 
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Return values 

Value Description 

S OK Fimction completed successfully. 

E_POINTER Invalid pointer. 

Notes: 

• When an ISpVoice object is first instantiated, it will have a volume of 
SPMAX_V6LUME. . 

• Volume is specified as a percent of the maximum volume of the current voice. Each 
voice implementation has its own maximum volume. 

• IhQpusVolume parameter must between 0 (SPMIN_VOLUME) and 100 
(SPMAX^VOLUME) inclusive. These values are contained in the SPVLIMITS 
enumeration sequence. 

© 1 995-_2000 Microsoft Corporation, AI [ rights reserved 



[This is preliminar}^ documentation and subject to change.] 

ISpVoice: : WaitUntilDone 

ISpVoice: rWaitUntilDone specifies the time interval in milliseconds that the engine should 
wait for all queued Speak and SpeakStream actions associated with this ISpYpice instance to 
have completed. Completion of a queued Speak or SpeakStream action is based on when an 
audio object has committedd its audio playing. 

HRESULT WaitUntilDone ( 
XJLONG msTimeout 

); 

Parameters 

fflsTlTHSOUt 

[in] Value specifying the time interval in milliseconds to wait before the WaitUntilDone 
method times out with an error. The WaitUntilDone method will not time out by 
specifying INFINITE for this value. 

Return values 

Value Description 

S OK Function completed successfully. 

S FALSE Wait time interval was exceeded. 

© L99S-2000 Microsoft Corporation. All rights reserved 
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ISp Voice: iSetSyncSpeakTimeout 

ISp Voice: zSetSyncSpeakTimeout sets the timeout interval in milliseconds after which, 
synchronous Speak and SpeakStream calls to this instance of ISpVoice will timeout. 

HRESULT SetSyncSpeakTimeout ( 
ULONG msTimeout 

); 

Parameters 

msTimeout 

[in] Value specifying the timeout interval in milliseconds for synchronous speech 
operations. The SetSyncSpeakTimeout method will not time out by specifying 
INFINITE for this value. 

Return values 

Value Description 

S OK Function completed successfully. 

E_INVALIDARG One or more arguments are invalid. 

Remarks 

• The timeout interval is set for each ISpVoice instance and by default it is set to 10 
seconds when the timeout interval is not specified in SetSyncSpeakTimeout. 

© 1995-2000 Micrpsoft_Cqrppra^^^ Ajln^ts reserved. 
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ISpVoice: :GetSyncSpeakTimeout 

ISpVoice: :GetSyncSpeakTimeout retrieves the timeout interval for synchronous speech 
operations for this ISpVoice instance. 

HRESULT GetSyncSpeakTimeout ( 
ULONG *pmsTimeout 

); 

Parameters 

pmsTimeout ^ , u 

[out] Address of the timeout interval in milliseconds for synchronous speech operations. 
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Return values 



Value 

S_OK 

E POINTER 



Description 

Fimction completed successfully. 
Invalid pointer. 



© l?95-2000_Microspft Corporatioit All rights resented 
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ISp Voice: rSpeakCompleteEvent 



ISpVoice::SpeakCompleteEvent returns an event handle used to wait until the voice has 
completed speaking. 

This is similar to the functionality provided by ISpVoice::WaitUntilDone , but allows the caller 
to wait on the event handle. The event handle is owned by this object and is not duplicated. 

The caller must neither call CloseHandle(), nor should the caller ever use the handle after 
releasing the COM reference to this object. 

[local] HANDLE SpeakCompleteEvent ( void ) ; 

Parameters 

None. 

Return values 

Value Description 

Event Handle For WAIT operation. 



© 1995-2000 Mtcrosoft Corporation All rights reserved . 
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ISp Voice: rIsUISupported 



ISpVoice::IsUISupported determines if the specified type of UI is supported. 



[local] HRESULT IsUISupported( 



const WCHAR -^pszTypeOfUI , 

vo id *pvExtraDa ta , 

ULONG cbExtraData, 

BOOL *pf Supported 



); 



Parameters 
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Parameters 

pszTypeOfUI , . , . - i 

[in] Address of the null-terminated string containing the UI type that is being quened, 

pvExtraData 

[in] Pointer to additional information needed for the object. 
cbExtraData 

[in] Size, in bytes, of the ExtraData. 

pfSupported ^ tti- • t. ttt* 

[out] Flag specifying whether the specified UI is supported. TRUE indicates the Ul is 
supported, and FALSE indicates the UI is not supported. 

Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG One or more arguments are invalid. 

FAILED(hr) Appropriate error message. 

© 19_95-20pp_Microsoft Cgg)orM reser\'ed. 



[ITiis is preliminar}^ documentation and subject to change.] M 

ISp Voice: :DisplayUI 

ISpVoice::DisplayUI displays the requested UI. 

[local] HRESULT DisplayUI ( 

HWND hwndPSLrent , 

const WCHAR -^pszTitle, 
const WCHAR -^pszTypeOfVI , 
void * pvExtraData, 

ULONG cbExtraDa ta 

); 

Parameters 

hwndParent 

[in] Specifies the parent window handle information. 
pszTitle^^^ Address of a null-terminated string containing the window title information. 

pszTypeOfUI _ . j- i 

[in] Address of the null-terminated string contammg the requested UI type to display. 

pvExtraData 

[in] Pointer to additional information needed for the object. 
cbExtraData 

[in] Size, in bytes, of the ExtraData. 

Return values 

Value Description 
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S OK Function completed successfully. 

EJNVALIDARG One or more arguments are invalid. 

FAILED(hr) Appropriate error message. 



© 1995-2000 Microsoft Corporation. All rights reserved 
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Appendix B 



[This is preliminary documentation and subject to change.] 

Engine-Level Interfaces 

This section describes the interfaces and methods for incorporating speech engines into applications. 
They are intended for use at the DDI or device driver interface level. Some managers or mterfaces 
may have entries also m the Appllcatipn-Leyel Inte^^^^ section. However, entries listed here apply 
only to the device driver or engine level. 

• Gremmar Compiler^M^ 

• kesource Manager 

• Speech Recognition M^iager 

• Speech Recognition Engine Manager 

• Te"xt-to-Speech Engine Manager 



Microsoft Speech SDK 
with SAPI 5.0 



) 19 95-20 00 Microsoft Corporation. All rights reserved. 
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[This is preliminary documentation and subject to change,] 

Grammar Compiler Manager (DDI-level) 

The following section covers: 

• ISpErrorLog 

• ISpGramCompBackend 

• ISpGrammarCompiler 

• ISpITNProcessor 

• ISpCFGEngineClient 

• ISpCFGInterpreter 

• ISpCFGInterpreterSite 



© 1995-2000 Microsoft Corporation. All rights reser\^ed. 
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ISpErrorLog 

Methods in Vtable Order 
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ISpErrorLog Methods Description 

AddError Writes an error to the log file. 



© 1995:20gO.MicrospACorppration.^^^^^^ reserved. 



[This is preliminai>' documentation and subject to change.] 

ISpErrorLog: -.AddError 

ISpErrorLog:: AddError writes an error to the log file. 

This function is application-defined and may be customized for the application's needs. By default, 
no action is performed. 

HRESULT AddError ( 

const long iLlneNimber, 
HRESULT hr, 
const WCHAR *pszDescription, 
const WCHAR *pszHelpFile, 
DWORD dwHelpContext 

); 

Parameters 

ILineNumber 

The line number of the error. 

hr 

The error code being logged. 
pszDescription 

A textual description of the error. 
pszHelpFile 

The file being written to. 
dwHelpContext 

Flags providing additional information for the log. 

Return values 

Value Description 

§ OK Function completed successfully. 

FAILED (hr) Appropriate error message. 

Because this method is appUcation defined, the retum value may change. See specific vendor 
documentation for details. 



©1995-2000^ Microsoft Corporation rights reserved. 



Microsofl Speech SDK 
with SAPI 5.0 



[This is preliminary documenialion and subject to change.] 
file://C:\WINDOWS\TEMPVhh38F6.htm 12/28/00 



Engine-Level Interfaces 



Page 3 of 75 



ISpGramCompBackend 



ISpGramCompBackend inherits from the ISpGrammarBuilder interface. 



Methods in Vtable Order 



ISpGramCompBackend Methods 
Se tSav eObjects 



InitFromBinarvGrammar 



Description 

Sets the storage location of the binary grammar. 
Initializes a grammar from binary data. 



©J995-2000_MjcrpsoiLCpj^)o^^^ 



[This is preliminary documentation and subject to change.] 




ISpGramCompBackend: : SetSaveObj ects 



ISpGramCompBackend: rSetSaveObjects sets the storage location of the binary grammar. 

When the ISpGrammarBuilder: :Commit method is called, the grammar compiler back end writes the 
binary grammar to the location of pStream. When caUing the SetSaveObjects method multiple times, 
the last call made before calHng the Commit method, receives the binary grammar. 

HRESULT SetSaveObjects ( 
IStream *pStream, 
I SpErr or Log *pErrorLog 

); 

Parameters 

pStream 

Address of the IStream that receives the binary grammar. 

pErrorLog ^ ^ . r 

Address of the ISpgrrorLog interface that receives the error information. 

Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG One or more arguments are invalid. 

FAILED(hr) Appropriate error message. 



© 1995-2000 Microsoft Corporation All rights reserved . 
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ISpGramCompBackend::InitFromBinaryGram 

ISpGramCompBackendirlnitFromBinaryGrammar initializes a grammar from binary data. 

HRESULT InitFromBinary Grammar { 

const SPBTOARYGRAMMAR *pBinaryData 

); 

Parameters 

pBinaryData 

Pointer to the grammar list. 

Return values 

Value Description 

S Qj<;^ Function completed successfully. 

E OUTOFMEMORY Exceeded available memory. 

FAILED (hr) Appropriate error message. 

©A?95:2pp0 Microsoft Corporation^ All rights j-eseryed. 

Microsoft Speech SDK 

with SAP! 5.0 ^^^^^^.^.^^ — " ^ 

[This is preliminary documentation and subject to change.] 

ISpGrammarCompiler 

Methods in Vtable Order 

ISpGrammarCompiler Methods Description 

CompileStream Loads the XML file into the DOM. 

© 1995-2000 Microsoft Cojrporat]on,MUlgbts_reser\'ed. 



[This is preliminary documentation and subject to change.] W 

ISpGrammarCompiler::CompileStreain 

ISpGrammarCompiler: zCompileStream loads the XML file into the DOM. 

Also loads the XML that contains the <DEFINE> in case it is different from the main file specified 
by -d flag. 

HRBSUIiT Con^ileStreamC 
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IStream 
IStream 
IStream 
IStream 



•^pSource, 
*pDest, 



*pHeader, 
*pDe finer 



ISpErrorLog *pErrorLogr 
DWORD dwFlags 

); 

Parameters 

pSource 

Pointer to the source. 

pDest 

Pointer to the destination. 
pHeader 

Pointer to the stream header. 
pDefine 

Pointer to the definition. 
pErrorLog 

Pointer to the error log receiving the messages. 
dwFlags 

[in] Not currently used. May be NULL. 
Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG One of the parameters is bad or invalid. 

FAILED (hr) Appropriate error message. 



ISpITNProcessor interface is implemented by SAPI to do the Inverse Text Normalization (ITN). 
Methods in Vtable Order 



© 1995-2000 Microsoft Cprporati_on, AH rights reserved 



Microsoft Speech SDK 
with SAPI 5.0 



[This is preliminaiy documentation and subject to change.] 



ISpITNProcessor 



ISpITNProcessor Methods 
Lo adlTNGrammar 



ITNPhrase 



Description 

Loads an inverse text normalization grammar. 
Parses an inverse text normalization phrase. 



© 1995:2000M9rpsoft Coiporation„ AU_righfe„resei>:ed 
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ISpITNProcessor : :LoadITNGrammar 

ISpITNProcessor::LoadITNGrainmar loads an inverse text normalization (ITN) grammar. The 
loaded grammar can be used by either SAPI or the speech recognition (SR) engine. 



HRESULT LoadlTNGrammar { 
WCHAR *pszCLSID 

); 

Parameters 

^^^^^A^ress of the null-terminated string containing the CLSID of the ITN grammar object 
implementing ISpCFGInterpreter. 

Return values 

Value Description 

g OK Function completed successfully. 

E POINTER p^zCLS/D is invalid or bad. 

FAILED(hr) Appropriate error message. 

© 1 995r2000_ Microsoft Corporation Ali rights reserved. 

[This is preliminaiy documentation and subject to change.] • 

ISpITNProcessor: rITNPhrase 

ISpITNProcessor: rITNPhrase parses an inverse text normalization (ITN) phrase. 

The ITNPhrase will attempt to parse the pPhrase passed in using the ITN grammar loaded by 
ISpITNProcessor::LoadITNGrammar. If a parse is found, the ITN grammar will add the display text 
replacement. For example, AddReplacement "$100" for "one hundred dollars". 

HRESULT ITNPhrase ( 

ISpPhraseBuilder *pPhrase 

); 

Parameters 

pPhrase 

Address of the phrase to parse. 

Return values 
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Value 

S_OK 

E_INVALIDARG 
SP_NO_RULE_ACTIVE 
E_OUTOFMEMORY 
FAILED(hr) 



Microsoft Speech SDK 
with SAPI 5.0 



Description 

Function completed successfully. 

No words are available. 

No rules are available. 

Not enough memory to complete operation. 

Appropriate error message. 



©J_?95-1000_MicrpspA Corporation _A11 rights reserved 
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[This is preliminary documentation and subject to change. ] 

ISpCFGEngineClient 

The ISpCFGEngineClient interface allows the CFG engine to notify the SR engine of changes in the 
status of loaded grammars. 

When to Implement 

Implemented by an SR engine. 
Methods in Vtable Order 



ISpCFGEngineClient Methods 
WprdNotify 

RuleNotife 



Description 

Notifies the SR engine of events related to the addition or 

deletion of words in the loaded grammars. 

Notifies the SR engine of events related to the addition, 

deletion, activation, or deactivation of rules in the loaded 

grammars. 

© 1995-2000 Microsoft Cprporation. All rights_resetved 
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[This is preliminary documentation and subject to change.] 

ISpCFGEngineClient: iWordNotify 

ISpCFGEngineClient: rWordNotify notifies SR engine of events related to the addition or deletion 
of words in the loaded grammars. 

Duplication words (from multiple grammars) are added only once. 



HRESULT WordNotify( 

SPCFGNOTIFY Action, 
ULONG cWords, 
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const SPWORDENTRY *pWords 

); 

Parameters 

Action 

The action being taken of type SPCFGNOTIFY. Must be either SPCFGN_ADD or 
SPCFGN__REMOVE. 
c Words 

The number of words in pWords. 
pWords 

An array of words for which Action specifies. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG One or more of the parameters are invalid. 

E_OUTOFMEMORY Exceeded available memory. 

E_FAIL Operation failed for unspecified reason. 

FAILED (hr) Appropriate error message. 



© 1995-2000 Microsoft Corporation All rights reserved . 
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ISpCFGEngineClient: .RuleNotify 

ISpCFGEngineClientrrRuleNotify notifies SR engine of events related to the addition, deletion, 
activation, or deactivation of rules in the loaded grammars. 

HRESULT RuleNotify ( 

SPCFGNOTIFY Action , 

ULONG cRules, 
const SPRULEENTRY -^pRules 

); 

Parameters 

Action 

The action being taken of type SPCFGNOTIFY. Must be either SPCFGN_ADD, 
SPCFGN_REMOVE, SPCFGN_ACTIVATE, SPCFGN_DEACTIVATE, or 
SPCFGN_INVALIDATE. 
cRules 

The number of rules in pRuIes. 
pRnles 

An array of rules for vAiich Action specifies. 
Return values 
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Value 

S_OK 

FAILED (hr) 



Description 

Function completed successfully. 
Appropriate error message. 



© 1995tMQ.¥icrospA^Coii)pratip!i All rights reserved. 
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ISpCFGInterpreter 



[This is preliminary documentation and subject to change.] 



ISpCFGInterpreter: rInitGrammar 



ISpCFGInterpreter: :InitGrammar 

HRESULT InitGrammar ( 

const WCHAR *pszGrammarNaxne , 
const void **pvGranmiarData 

); 

Parameters 

pszGrammarName 



Methods in Vtable Order 



ISpCFGInterpreter Methods 

InitGrammar 

In ter pret 



Description 



© 1995-2000 Microsoft Corporation. AH rights reserved 





Return values 



Value 

S_OK 

FAILED(hr) 



Description 

Function completed successfully. 
Appropriate error message. 



© 1 995-2000 Microsoft Corporation _ All. rights reserc'ed. 
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[This is preliminary documentation and subject to change.] 

ISpCFGInterpreter : :Interpret 

ISpCFGInterpreter: rlnterpret 



HRESULT Interpret ( 



); 



const ULONG 
const ULONG 

ISpCFGInterpreterSite 



Parameters 

pPhrase 
[in] 

ulFirstElement 
[in] 

ulCountOfElements 
[in] 

pSite 

[in] 

Return values 

Value 

S_OK 

FAILED(hr) 



^pPhrase, 
UlFirstElement , 
ulCoun tOfEl ements , 

*pSl te 



Description 

Function completed successfully. 
Appropriate error message. 



© 1995-2000 Microsoft Corporation AH rights reserved 
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[This is preliminar>^ documentation and subject to change,] 

ISpCFGInterpreterSite 

Methods in Vtable Order 



ISpCFGInterpreterSite Methods 
AddTextReplaceinent 
AddP^roperty 
GetResourceValue 



Description 

Adds one text replacement to the phrase. 
Adds a property entry to the phrase object. 
Retrieves the resource information for a grammar. 



© 1995-2000 Microsoft Corporation _AU rightsresewed 
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[This is preliminary documentation and subject to change.] ^ 

ISpCFGInterpreterSite::AddTextReplacement 

ISpCFGInterpreterSiteitAddTextReplacement adds one text replacement to the phrase. The 
object must have been initialized by calling SetPhrase prior to calling this method. 

HRESULT AddTextReplacement ( 

S PPHRAS ERE PLACEMENT *pRepla ce 

); 

Parameters 

pReplace^ Address of the SPPHRASEREPL ACEMENT that contains the replacement text. 
Return values 

Value Description 

S OK Function completed successfully- 

E INVALID ARG cReplacements is zero or pReplace is invaUd. 

SPERR_UNINITIALIZED The object is uninitialized. 

FAILED(hr) Appropriate error message. 

© 1995-20pp_Microsofl Corppiati(>n _ Alljights reserved 

[This is preliminarv^ documentation and subject to change.] 

ISpCFGInterpreterSite::AddProperty 

ISpCFGInterpreterSiterrAddProperty adds a property entry to the phrase object. 

HRESULT AddProperty( 

SPPHRASEPROPERTY *pProperty 

); 

Parameters 

^^'^^^[^ Address of the SPPHRASEPROPERTY structure that contains the property information. 
Return values 
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Value 

S_OK 

E_INVALIDARG 

SPERR__UNINITIALIZED 

FAILED(hr) 



Description 

Function completed successfully. 
pProperty is bad or invalid. 
The object is uninitialized. 
Appropriate error message. 



© 1995-2000 Microsoft Corporation. AH rights reserved . 
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ISpCFGIiiterpreterSite::GetResourceValue 

ISpCFGIiiterpreterSite::GetResourceValue retrieves the resource information for a grammar. 

HRESULT GetResourceValue ( 

const SPRtTLEHANDLE hRule, 

const WCHAR ^pszResourceNaxae , 

WCHAR '^■*^ppCoMemResource 

); 

Parameters 

hRule , 

[in] The rule handle containing the valid rule ID and mdex. 

TJSzR^SOtifCCl^ClTHC 

[in] The name of the resource from which to retrieve the grammar information. 
ppCoMemResource 

[out] Pointer containing the passed back resource value. 

AppUcations implementing this method must call CoTaskMemFreeQ to free memory 
associated v^ith this resource. 



Return values 

Value 

S_OK 

E_INVALIDARG 

E_OUTOFMEMORY 

FAILED(hr) 



Description 

Function completed successfully. 
One of the parameters is bad or invalid. 
Exceeded available memory. 
Appropriate error message. 



© 1995-_2000_Microsoft Corporation^ Ail rights^reserved 
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Resource Manager (DDI-level) 
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The following section covers: 

• ISpObjectTokenEnumBuilder 

• ISpTokenyi 

• ISpTaskManager 

• ISpThreadControl 

• ISpTt^eadTask 



© 1 995-2000 Microsoft Corpgr_atipn .Alljights reserved 
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with SAPI 5,0 - ^ 

[This is preliminaiy documentation and subject to change.] 

ISpObjectTokenEnumBuilder 

This interface inherits from lEnumSpObjectTokens . 
Methods in Vtable Order 

ISpObjectTokenEnumBuilder Description 
Methods 

SetAttribs Sets the required and optional token enumerator attribute 

information. 

AddTokens Adds tokens to the object token enumerator. 

AddTokensFromPataKey Adds a new token using specified subkey and Categoryld 

information. 

AddTokensFromTokenEnum Adds a new token from an enumerated list of object 

tokens. 

Stjrt Sorts the list of enumerated object tokens. 

© 1 995-2000 Microsoft Corporatiori . Ml rj^hts„reserved. 

[This is preliminary documentation and subject to change.] *™ 

ISpObjectTokenEnumBuilder::SetAttribs 

ISpObjectTokenEnumBuilder::SetAttribs sets the required and optional token enumerator 
attribute information. 

HRESULT SetAttribs ( 

const WCHAR *pszReqAttribs, 
const WCHAR *pszOptAttribs 

)} 

Parameters 
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pszReqAttribs 

Address of a null-terminated string containing the required attribute information. 

pszOptAttribs i -i • ^ 

Address of a null-terminated string containing the optional attnbute mtormation. 

Return values 



Value 

S_OK 

SPERR„ALREADY_.INITIALIZED 

E_OUTOFMEMORY 

FAILED(hr) 



Description 

Function completed successfully. 
The object has already been initialized. 
Exceeded available memory. 
Appropriate error message. 



995-2000 Microsoft Corporation^ AlLnS.l>ts reserved. 



[This is preliminary documeniaiion and subject to change,] 

ISpObjectTokenEnumBuilder::AddTokens 

ISpObjectTokenEnumBuilder::AddTokens adds tokens to the object token enumerator. 

HRESULT AddTokens( 

ULONG cTokens, 
ISpOb j ectToken * *pTok.en 

); 

Parameters 

cTokens 

The number of object tokens being added to the sequence. 

^^^^^ Address of a pointer to an ISpObj ectToken object containing the information associated with 
the tokens being added. 

Return values 

Value Description 

S OK Function completed successfully. 

E INVALID ARG One or more arguments are invalid. 

E_POINTER Invalid pointer. 

E OUTOFMEMORY Exceeded available memory. 

SPERR__UNINITIALIZED The object has not been properly initialized. 

FAILED(hr) Appropriate error message. 

© 1995j-2000 Microsoft Cgiporation „A11_ rights reserved 
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[This is preliminary documentation and subject to change.] 

ISpObjectTokenEnumBuilder::AddTokensFro 

ISpObjectTokenEnumBuilderzrAddTokensFromDataKey adds a new token using specified 
subkey and Categoryld information. 

HRESULT AddTokensFromDataKey ( 

ISpDataKey *pDa taiCey , 
const WCHAR *pszSubKey, 
const WCHAR *pszCategoryId 

); 

Parameters 

vDataKey . , ^ ^^1.^1 

Address of an ISpDataKey interface that specifies the system registry key to create the token 

from. 

pszSubKey ^ , , 1 * x- 

Address of a null-terminated string containing the system registry subkey intormation. 

pszCategoryld ^ . . -x- • +u 

Address of a null-terminated string containing the category identifier information tor the 

system registry subkey. 
Return values 

Value Description 

S OK Function completed successfully, 

E INVALID ARG One or more arguments are invalid. 

SPERR_UNINITIALIZED The object has not been properly initialized. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation. All rights resented 

[This is preliminary documentation and subject to change.] 

ISpObjectTokenEnumBuilder::AddTokensFro 

ISpObjectTokenEnumBuilderrrAddTokensFromTokenEnum adds a new token from an 
enumerated list of object tokens. 

HRESULT AddTokensFromTokenEnum ( 

lEnumSpObjectTokens *pTokenEnum 

); " 
Parameters 

^^^^^SXess of an lEnumSpObiectTokens interface containing the list of enumerated object tokens 
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to add. 



Return values 



Value 

S_OK 

E_,INVALIDARG 

SPERR_UNINITIALIZED 

FAlLBD(hr) 



Description 

Function completed successfully. 

One or more arguments are invalid. 

The object has not been properly initialized. 

Appropriate error message. 



© i995-2p00_Mlcrpspft_CojjDprato _ AlLnghte reserved. 
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ISpObjectTokenEnumBuilder: :Sort 



ISpObjectTokenEnumBuilder::Sort sorts the list of enumerated object tokens. 

HRESULT Sort( 

const WCH21R *pszTokenIdToLlstFirst 

); 

Parameters 

pszTokenldToListFirst 

Address of a null-terminated string specifying the identifier of the first token in the sorted list. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_POINTER Invalid pointer. 

SPERR_IJNINITIALIZED The object has not been properly initiaUzed. 

FAILED(hr) Appropriate error message. 



PAJ^^>299^yM\'^^^9^^9S9<il^^o^' All.riglits reserved 



Microsoft Speech SDK 
with SAP! 5.0 




[This is preiiminary documentation and subject to change,] 



ISpTokenUI 



Methods in Viable Order 
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ISpTokenUI Methods Description 

IsUISupported Determines if the specified UI type is supported by the 

token. 

DispJayUI Displays the UI associated with the object token. 

® l995-2000MkmofiCojpqmioa, All rights reseival 
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[This is preliminary documentation aiid subject to change.] 

ISpTokenUI: rlsUISupported 

ISpTokenUI: rIsUISupported determines if the specified UI type is supported by the token. 

[local] HRESULT I sUI Supported ( 

const WCHAR *pszTypeOfUI, 

void *pvExtraData, 

ULONG cbEx traDa ta , 

lUnknown *pnxikObj ect, 

BOOL -^pf Supported 

); 

Parameters 

pszTypeOfUI . . ^ ... tit. 

[in] Address of a null-terminated string contammg the object s UI type. 

pvExtraData 

[in] Pointer to additional information needed for the object. 
cbExtraData 

[in] Size, in bytes, of the ExtraData. 
punkObject 

[in] Address of the object's lUnknown interface. 

;?^wp;?orJ^ of a variable that receives the value indicating support for the interface. This 

value is set to TRUE when this interface is supported and FALSE otherwise. 

Return values 

Value Description 

S Function completed successfully. 

E INVALID ARG One or more arguments are invalid. 

E__POINTER Invalid pointer. 

© l_995-2000Mcrosoft Cpiporatioa AH rights reserved 
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ISpTokenUI: :DispIayUI 
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ISpTokenUI::DisplayUI displays the UI associated with the object token. 

[local] HRESULT DisplayUI ( 



HWND 

const WCHAR 
const WCHAR 
void 
ULONG 

lUnknown 



hwndParent, 
*pszTitle, 
-^pszTypeOfUI, 
*pvExtraDa ta , 

cbExtraData, 
*p Token r 
*punkObj ect 



); 

Parameters 

hwndParent 

[in] Specifies the handle of the parent window. 
pszTitle 

[in] Address of a null-terminated string containing the window title. 
pszTypeOfUI 

[in] Address of a null-terminated string containing the UI type to display. 
pvExtraData 

[in] Pointer to additional information needed for the object. 
cbExtraData 

[in] Size, in bytes, of the ExtraData. 
pToken 

[in] Address of the ISpObjectToken containing the object token identifier. 
punkObject 

[in] Address of the lUnknown interface pointer. 

Return values 



Value 

S__OK 

E_^INVALIDARG 
E POINTER 



Description 

Function completed successfully. 
One or more arguments are invalid. 
Invalid pointer. 



Microsoft Speech SDK 
with SAPI 5.0 
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[This is preliminary documentation and subject to change.] 

ISpTaskManager 

When to Implement 

This interface is used to implement a task management service provider to optimize thread usage. 
Methods in Vtable Order 
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ISpTaskManager Methods 
SetThreadPopUnfo 
G etT hreadPoolInfo 
QueueTask 

CreateR^^ 

Cre ateThreadControl 

Term inateTask 

TerminateTaskGroup 



Description 

Sets the attributes for thread pool management. 
Retrieves the current thread pool management attributes. 
Adds a task to the queue for asynchronous task 
processing. 

Creates a task entry that will be processed on a high 
priority thread. 

Creates a thread control object. 
Interrupts a specified task. 

Terminates a group of tasks that match a specific group 
identifier. 



© 1 995-2000 Microsoft Corporation_A]l_rights_reserved. 



[This is preliminarv' docmiientation and subject to change.] 

ISpTaskManager: iSetThreadPoolInfo 

ISpTaskManager: :SetThreadPoolInfo defines the thread pool attributes. 

HRESXJLT SetThreadPoolInf o ( 

cons t SPTMTHRSAD INFO *pPool Inf o 

); 

Parameters 

pPoolInjb ^^^^^^^ ^ SPTMTHREADINFO structure that receives the thread management 
information. 



Return values 

Value 

S_OK 

E__INVALIDARG 
FAILED (hr) 



Description 

Fimction completed successfully, 

pPoolInfo is invalid or pPoolInfo->lPoolSize size is less 

than-1. 

Appropriate error message. 

© t9_95-2000 Micrgsofti:qrppratm AU„ rishts.reseryed 
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ISpTaskManager: : GetThreadPoolInfo 
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ISpTaskManager::GetThreadPoolInfo retrieves the current thread pool management attributes. 

HRESULT GetThreadPoolInf o { 

SPTMTHRBADINFO *pPool Info 

); 

Parameters 

Address of an SPTMTHREADINFO structure that contains the current thread 
management information. 

Return values 

Value Description 

§ OK Function completed successfully. 

E POINTER pPoolInfo is invalid or bad. 

FAILED (hr) Appropriate error message. 



© 1 99Jji20pO Microsoft Cj?rf>orat 
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ISpTaskManager : iQueueTask 

ISpTaskManager::QueueTask adds a task to the queue for asynchronous task processing. 

HRESULT QueueTask( 

ISpTask pTask, 
void *pvTaskData, 
HANDLE hCompEven t , 
DWORD* *pdwGroupIdf 
DWORD* *pTaskJD 

); 

Parameters 

pTask ^ , 

[in] Address of an ISpTask interface contaimng the task. 

pvTaskData 

[in] Address of the task data. 
hCompEvent 

[in] Handle of the task completion event. 

pt/wGrowp/J ^ Value specifying the identifier for the task group. This value may be NULL. 
pTaskID 

[out] Value specifying the task identifier. 
Return values 
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Value 

E_INVALIDARG 
E_^POINTER 
FAILED (hr) 



Description 

Function completed successfully. 
pTask is invalid or bad. 
pTaskId or pdwGroupId is invalid or bad. 
Appropriate error message. 



© 1995-2000 Microsoft Corporation. All rights reserved 



[This is preliminar)^ documentation and subject to change.] 




ISpTaskManager : : CreateReoccurringTask 



ISpTaskManagerriCreateReoccurringTask creates a task entry that will be processed on a high 
priority thread when the ISpTask::Execute method is called. 

These reoccurring tasks are designed to supply data to hardware devices. 

HRESULT CreateReoccurringTask ( 



I SpNo t i f yS ink * *ppTaskCtrl 

); 

Parameters 

pTask 

[in] Address of an ISpTask interface containing the task. 
pvTaskData 

[in] Address of the task data. 
hCompEvent 

[in] Handle of the task completion event. 
ppTaskCtrl 

[out] Address of a pointer to an ISpNotifySink interface that receives the task notifications. 
Return values 

Value Description 

S_OK Function completed successfully. 

E^INVALIDARG pTask is invalid or bad. 

E_POINTER ppTaskCtrl is invalid or bad. 

FAILED (hr) Appropriate error message. 



ISpTask 

void 

HANDLE 



* pvTaskData, 
hCompEvent , 



© 1 995-2000 Microsoft Corporation. AW rights reserved 
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ISpTaskManager::CreateThreadControl 

ISpTaskManager::CreateThreadControl allocates a thread control object. It does not allocate a 
thread. If the task managers controlling lUnknown has been allocated by ADDREF since the thread's 
creation, the allocated tluread control object uses the thread pool in the task manager. 

HREStJLT CreateThreadControl { 

.5SpTlxreadTa sk *pTask , 

void ^pvTaskData, 
1 ong nPri or i ty, 

ISpThreadControl **ppTaskCtrl 

); 

Parameters 

pTask 

[in] Address of the ISpThreadTask interface that is used to initialize and execute the task 
thread. 
pvTaskData 

[in] Data passed to all ISpThreadTask member functions. This value can be NULL. 
nPriority 

[in] The Win32 priority for the allocated thread. 
ppTaskCtrl 

[out] Address of a pointer to an ISpThreadControl interface that receives the thread control 
Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG pTask is invalid or bad. 

E_POINTER ppThreadCtrl is invalid or bad. 

E_OUTOFMEMORY Exceeded available memory. 

FAILED (hr) Appropriate error message. 

©_1 995-2000 Microsoft Corpomtipn AU rights reserved 
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ISpTaskManager : iTerminateTask 

ISpTaskManager::TerminateTask interrupts the specified task. 

HRBSULT TerminateTask { 
DWORD dwTaskId, 
ULONG ulWaitPeriod 

); 

Parameters 
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dwTaskId 

[in] Value specifying the identifier of the task to interrupt. 
ulWaitPeriod 

[in] Number of milliseconds to wait before interrupting the task. 
Return values 



Value Description 

S_OK Function completed successfully. 



ISpTaskManager::TerminateTaskGroup 



ISpTaskManager::TerminateTaskGroup terminates a group of tasks matching the specified group 
identifier. 

HRESULT TenninateTaskGroup ( 
DWORD dwGroupId, 
ULONG ulVJai tPeri od 

); 

Parameters 

dwGroupId 

[in] Value specifying the identifier for the task group to interrupt. 
ulWaitPeriod 

[in] Number of milliseconds to wait before interrupting the task group. 
Return values 

Value Description 

S_OK Function completed successfully. 

FAILED (hr) Appropriate error message. 



S^FALSE 
FAILED (hr) 



Method timed out. 
Appropriate error message. 



© 1993^900 Mcvosof^^ All rights„reserved 
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ISpThreadControl 
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The ISpThreadControl interface inherits from the ISpNotif^Sink interface. 
Methods in Vtable Order 



TerminateThread 

ThreadHaadle 

Threadid 

No tifyEvent 

WindowHandle 

ThreadCompleteE^^^ 

ExitThreadEvent 



[This is preliminar}^ documentation and subject to change.] 



ISpThreadControl: : StartThread 



ISpThreadControl::StartThread initiaUzes a thread and returns a window handle. 

HRESULT StartThread { 
DWORD dwFlags, 
HWND *phwnd 

); 

Parameters 



Optional address of an handle to a window. The handle of the new window will be returned to 
phwnd if this parameter is non-NULL. A window will not be created if this parameter is 
NULL. 



ISpThreadControl Methods 

StartThread 

WaitForThreadDpne 



Description 

Initializes a thread and returns a window handle. 
Specifies the time interval to wait before ending thread 
processing. 



©1995:2000 Microspft_Corppra^^^^^ ri^its reserved 




dwFlags 



Currently not implemented. 



Return values 



Value 

S_OK 

E_INVALIDARG 

E_POINTER 

E OUTOFMEMORY 



Description 

Function completed successfully. 
One or more arguments are invalid. 
Invalid pointer. 
Exceeded available memory. 
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ISpThreadCoiitrol::WaitForThreadDone 



ISpThreadControlrrWaitForThreadDone specifies the time interval to wait before ending thread 
processing. 

HRESULT WaitForThreadDone( 



HRE SULT *phjrThjrea dResult, 
UIiONG msTimeOut 

); 

Parameters 

jForceStop 

Flag specifies to stop thread processing. Thread processing will stop if the value is TRUE and 

contmue if FALSE. 
phrThreadResult 

Address of a handle to a COM return value. 
msTimeOut 

Time-out interval in milliseconds to wait before interrupting the task. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG One or more arguments are invalid. 



ISpThreadControl::TerminateThread 



ISpThreadControl::TerminateThread 

HRESULT TerminateThread { void ) ; 

Parameters 

None. 

Return values 



BOOL 



f Forces top J 



p 1995-2000 Microsoft Corppmtipn, All right s reserved. 
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Value 

S_OK 

E INVALID ARG 



Description 

Function completed successfully. 
One or more arguments are invalid. 



j995:20_00. Microsoft Corporation, All. rights res_erved. 
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ISpThreadControl: :ThreadHandle 



ISpThreadControl::ThreadHandle retrieves a thread handle. 

HANDLE ThreadHandle ( void ) ; 

Parameters 

None. 

Return values 

Value Description 

S OK Method completed successfully. 



[This is preliminar>^ documentation and subject to change.] 



ISpThreadControl: :ThreadId 



ISpThreadControl: :ThreadId 

DWORD Threadid ( void ) ; 
Parameters 

None. 

Return values 

Value Description 



© 1 995-2000 Microsoft Coiporation_^All rights reserved 
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ISpThreadControl: :NotifyEvent 

HANDLE NotifyEvent ( void ) ; 

Parameters 

None. 

Return values 

Value Description 

O 1995-2000 Mcwsoft Corporal 

[Tills is preliminm' documentation and subject to change.] 

ISpThreadControl: : WindowHandle 

ISpThreadControl: : WindowHandle 

HWND WindowHandle ( void ) ; 

Parameters 

None. 

Return values 

Value Description 

S_OK Method completed successfully. 

© ] 995-2000 Microsoft Cgrppration^ AH rights reserved 

[This is preliminaty documentation and subject to change,] 

ISpThreadControl: :ThreadCompleteEvent 

ISpThreadControl::ThreadCompleteEvent 
HANDLE ThreadCompleteEvent ( void ) ; 
Parameters 

None. 
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Return values 

Value Description 

S OK Method completed successfully. 



© 1995-2000 Microsoft Corporation. All rights reserved . 



[This is preliminary documentation and subject to change,] 

ISpThreadControhrExitThreadEvent 

ISpThreadControl::ExitThreadEvent 
HANDLE ExitThreadEvent (void) ; 
Parameters 
none. 

© 1995-2000 Micro_s_oft Corporation.. Alirights reserved. 

Microsoft Speech SDK 

with SAPI 5.0 S» 

[This is preliminary documentation and subject to change.] 

ISpThreadTask 

The ISpThreadTask interface simplifies thread-based operations. It allows SAPI to handle specific 
aspects of threads and thereby avoiding more complex Win32 operations. 

When to Implement 

If appUcations need this interface, there are three methods that need to be implemented and they are 
application specific. These methods may also be defined in more than once instance. 

Note: 

This is not a COM interface. 
Methods in Viable Order 

ISpThreadTask Methods Description 

InitThread Attempts to create a thread. 

ThreadProc Implements the processing of the thread. 

WindowMessage Implements the processing of window messages. 
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ISpThreadTask: .InitThread 

ISpThreadTask::InitThread attempts to create a thread. The thread is created only if it has 
successfully met the application's criteria. This method is an alternative to creating a thread from 
Win32 functions. 

virtual HRESULT STDMETHODCALLTYPE InitThread ( 

void *pvTaskDatar 

HWND hwnd 
) = 0; 

Parameters 

pvTaskData 

[in] The specific information for the application. 

hwnd 

[in] A window handle. 
Return values 

S_OK Function completed successfully. 

S_F AILED Function failed and should not create a new thread. 

© l_995-2000_Micrps_oft_Cpn>PL^^ All rights xeseryed 
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ISpThreadTask: :ThreadProc 

ISpThreadTask: rThreadProc implements the processing of the thread. This method will be 
application specific. 

virtual HRESULT STDMETHODCALLTYPE ThreadProc ( 

void * pvTaskData, 

HANDLE hExi tThreadEvent , 

HANDLE hNotifyEvent, 

HWND hwndWorker, 

volatile const BOOL *pfContinueProcessing 
) = 0; 

Parameters 

"^pvTaskData 

[in] The specific information for the application. 
hExitThreadEvent 
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[in, out] A handle to a thread object or an array of thread objects. 
hNotifyEvent 

[in] A handle to the notification event. 
hwndWorker 

[in] A window handle. 
pfContinueProcessing . i 

[in] Boolean flag indicating whether to continue processing. TRUE indicates the process 

should continue; FALSE otherwise. 

Return values 

S OK Function completed successfully. 

S FAILED Function failed. 

© 1995-2000 Microsoft Corporation, Ati rights reserved . 



[This is preliminary' documentation and subject to change.] ^ 

ISpThreadTask: tWindowMessage 

ISpThreadTask::WindowMessage implements the processing of window messages. Not all 
applications will need a window and this method may be left unimplemented. However, SAPI 
maintains a hidden window and messages posted will require this method. 

virtual LRESULT STDMETHODCALtiTYPE WindowMessage ( 
void *pvT'asJcPa ta , 

UINT Msg, 

WPARAM wParam, 

LP ARAM IParam 
> = 0; 

Parameters 

pvTaskData 

[in] The specific information for the appUcation. 

hWnd 

[in] A window handle. 

Msg 

[in] The type of window message. 

wParam ^ ^ . i 

Application-specific information. This will change based on the Msg value. 

IPctrcifH 

Application-specific information. This will change based on the Msg value. 
Return values 

The return value is application specific. 

©.l?95-2000Mcrosoft CojEoration. AJl rights.reseryed 
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[This is preliminary documentation and subject to change.] 

Speech Recognition Manager (DDI-level) 

The following section covers: 
• ISpPhraseBxulder 

© 1995-2000 Microsoft Coi^^ Albrights reser\'ed 
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[IMs is preliminar>^ documentation and subject to cbaoge,] 

ISpPhraseBuilder 

Note: The ISpPhraseBuilder interface inherits from ISpPhrase. 
Methods in Vtable Order 

ISpPhraseBuilder Methods Description 
InitFromPhrase Initializes from a phrase. 

I nitF romSerializedPhrase Initializes a phrase from a serialized phrase. 

Ad dElements Adds a copy of the given element to the end of this 

object's element list. 

AddRules Adds phrase rules to the phrase object. 

AddProperties Adds property entries to the phrase object. 

AddReplacemenis Adds one or more text replacements to the phrase. 

0 1995-2000 Microsoft Corporation All rights resen'ed 



[This is preliminary documentation and subject to change] 

ISpPhraseBuilder::InitFromPhrase 

ISpPhraseBuilder: :InitFromPhrase initializes from a phrase. 



HRESULT InitFromPhrase ( 

const SPPHRASE *pSrcPhrase 

); 

Parameters 

pSrcPhrase 
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Address of a SPPHRASE data structure containing the phrase information. IfpSrcPhrase is 
NULL, then the object is reset to its initial state. 

Return values 

Value Description 

S OK Function completed successfully. 

E~INV ALIDARG pSrcPhrase or pSrcPhrase->Rule,pNextSiblmg is invalid 

or bad. Alternatively, pSrcPhrase->LangID may be zero or 
pSrcPhrase->cbSiz€ does not indicate the same size as 
pSrcPhrase. 

FAILED(hr) Appropriate error message. 

Example 

The following code snippet demonstrates creating and initializing from a phrase. 

HRESULT hr; 

CComPtr<ISpPhraseBuilder> cpPhraseBuilder ; 
CComPtr<ISpPhrase> cpPhrase; 
CSpPhrasePtr pPhrase ; 

hr = cpPhraseBuilder. CoCreateInstance( CLSID__SpPhraseBuilder ); 
//Check return value 

hr = GetStdRecognition_Phrase { &cpPhrase, CLSID_SpSharedRecogognizer ); 

hr = cpPhrase- >GetPhrase (&pPhrase ); 
//Check return value 

hr ^ cpPhraseBuilder- >InitFromPhrase ( pPhrase ); 
/ /Check return value 

©J995:2000„M]crosoft Corppjation^ AU__Figh> reserved 



[This is preliminaiy documentation and subject to change.] 

ISpPhraseBuilder::InitFromSerializedPhrase 

ISpPhraseBuilder::InitFromSerializedPhrase initializes a phrase from a seriaUzed phrase. 

HRESULT InitFromSerializedPhrase ( 

const S PSERI ALT ZSDPHRASS -CpPhrase 

); 

Parameters 

T? Phvcisc 

Address of the SPSERIALIZEDPHRASE structure that contains the phrase information. 
Return values 
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Value 

S__OK 

E INVALIDARG 



FAILED(hr) 



Description 

Function completed successfully. 

pSrcPhrase or pSrcPhrase'>cbSerializedSize is invalid or 
bad. 

Appropriate error message. 



Example 



The following code fragment demonstrates InitFromSerializedPhrase. 



HRESULT hr; 

CComPtr<ISpRecoResult> 

CComPtr<ISpPhraseBuilder> 

SPSERIALIZEDPHRASE 

SPSERIALIZEDPHRASE 

ULONG 

CComPtr<IStream> 



RecoResult ; 

pPhraseBuilder ; 
*SerializedPhrase=NULL ; 
*pSerPhrase=NULL ; 

SerSize; 

cpStream; 



LARGE_INTEGER 1 iZero = { 0 , 0 } ; 

hr = Init { &cpRecoResult ) ; 
// Check result 

// Get SerializedPhrase 

hr = cpRecoResult->GetSerializedPhrase (&pSerializedPhrase) ; 

if (SUCCEEDED (hr) ) 

// Check for pSerializedPhrase 1= NULL 

CreateStreatnOnHGlobal (NULL, true, &cpStream) ; 

if (cpStream) . 

hr = cpStream- >Write (pSerializedPhrase, pSerializedPhrase- >ulSerializedSiz 

hr = cpStream- >Seek{liZero, STREAM_SEEK_SET, NULL) ; 
if (SUCCEEDED (hr) ) 

hr = cpStream- >Read( (void *)&SerSize, sizeof (SerSize) , NULL) ; 

pSerPhrase = (SPSERIALIZEDPHRASE*) : : CoTaskMemAlloc (SerSize) ; 

hr = cpStream- >Seek(liZero, STREAM_SEEK_SET, NULL) ; 
if (SUCCEEDED (hr) ) 

hr = cpStream- >Read( (void *) pSerPhrase, SerSize, NULL) ; 

hr = cpPhraseBuilder.CoCreateInstance( CLSID_SpPhraseBuilder ); 
// Check result 

hr = cpPhraseBuilder->InitFromSerializedPhrase ( pSer Phrase ); 
// Check result 

: :CoTaskMemFree ( pSerializedPhrase ); 



© 1995-2000 Microsoft Corporation All _rj£hts_reseryed 



This is preiiminar}^ documentation and subject to change.] 




ISpPhraseBuilder : : AddElements 
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ISpPhraseBuiIder::AddEIements adds a copy of the given element to the end of this object's 
element list. 

HRESULT AddElements ( 

ULONG cEl emen t s , 

const SPPHRASEELEMENT *pElement 

) ; 

Parameters 

cElements 

Specifies the number of phrase elements to add. 
pElement 

Address of the SPPHRASEELEM^^ data structure containing the phrase element to add. 
Return values 

Value Description 

S_OK Function completed successftilly. 

E INVALIDARG One or more arguments are invalid. 

SPERR_UNINITIALIZED The object has not been properly initialized. 

FAILED(hr) Appropriate error message. 

(D 1995-2000 Microsoft Corporation All rights reserved. 
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ISpPhraseBuilder: : AddRules 

ISpPhraseBuiIder::AddRules adds phrase rules to the phrase object. 

HRESULT AddRules ( 

const SPPHRASERULEHANDLE hParent, 
const SPPHRASERULE *pRule, 
SPPHRASERULEHANDLE *phNewRule 

); 

Parameters 

hParent 

Handle to the parent phrase rule. 

pRule 

Address of the SPPHRASERUL structure that contains the phrase rule information. 
phNewRule 

Address of the SPPHRASERULEHANDLE structure that contains the new phrase rule 
information. 

Return values 
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Value 

S_OK 

E_POINTER 

SPERR_UNINITIALIZED 
FAILED(hr) 



Description 

Function completed successfully. 
Invalid pointer. 

The object has not been properly initialized. 
Appropriate error message. 



© 1995-2000 Microsoft Corporation All rights reserved 
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ISpPhraseBuilder : : AddProperties 

ISpPhraseBuiIder::AddProperties adds property entries to the phrase object. 

HRESULT AddProperties { 

const SPPHRASEPROPERTYHANDLE hParent, 
const SPPHRASEPROPERTY *pProperty, 
SPPHRASEPROPERXYHA^ *phNewProperty 

); 

Parameters 



hParent 

Handle to the parent phrase element. 
pProperty 

Address of the SPPHRASEPROPERTY structure that contains the property information. 
phNewProperty 

Address of the SPPHRASEPROPERTYHANDLE structure that contains the new property 
information. 

Return values 



Value 

S_OK 

E_INVALIDARG 
E_POINTER 

SPERR_UNINITIALIZED 

SPERR_ALREADY_INITIALIZED 

FAILED(hr) 



Description 

Function completed successfully. 
One or more arguments are invalid. 
Invalid pointer. 

The object has not been properly initialized. 
The object has already been initialized. 
Appropriate error message. 



) 1995-2000 Microsoft CorpoTation All rights reserved 



[This is preiiminary documentation and subject to change] 

ISpPhraseBuilder::AddReplacements 
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ISpPhraseBuilder::AddReplacements adds one or more text replacements to the phrase. 

HRESULT AddReplacements { 

ULONG cReplacements f 

const SPPHRASERSPLACEMENT *pReplacements 

); 

Parameters 

cReplacements 

The number of replacement phrase elements. 

vReplacements ... t . 

Address of the SPPHMSEREPLA^ structure that contains the phrase element 

replacement information. 
Return values 

Value Description 

S OK Function completed successfully. 

E_INVALIDARG One or more arguments are invalid. 

SPERR__UNINITIALIZED The object has not been properly initialized. 

FAILED(hr) Appropriate error message. 

© i 995-2000 Microsoft CprjDoratipn „ All. rights/eserved. 

Microsoft Speech SDK . .^v 

with SAPI 5.0 ^ 

[This is preliminary documentation and subject to change.] 

Speech Recognition Engine Manager (DDI- 
level) 

The following section covers: 

• ISpPrivateEngineCall 

• ISpSREngine 

• iSpSREngineSite 

• iSpSRAitemates 

®.1995-2p00_MicrgsoftCoiEoration Alljighte reserved 

Microsoft Speech SDK 

with SAPI 5.0 W 



[This is preliminary' documentation and subject to change. 

ISpPrivateEngineCall 
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When to Implement 

Implemented by SAPI and inherits from ISpR ecoContext . Private Engine Call is initialized by the 
engine extension object while it is being created. 



Methods in Viable Order 

ISpPrivateEngineCall Methods 
CallEngme 



Description 

Allov^s an engine-specific call. 



© 1995-2000 Microsoft Con>pratipn.^^^ 



[This is preliminary^ documentation and subject to change,] 

ISpPrivateEngineCall::CallEngine 

ISpPrivateEngineCall: rCallEngine allows an engine specific call. 
It is called from the engine extension object to the engine object. 

HRESULT CallEngine{ 
PVOID pCallFrame, 
DLONG ulCall Frame Si ze 

); 

Parameters 

pCallFrame 

[in, out] The engine-specific structured block of memory parameters. This block will be 
marshalled in the shared engine case and must not contain pointers to other memory 
allocations. It must be fully self-contained and relative only to itself 
ulCallFrameSize 

[in] Size, in bytes, of the pCallFrame structure. 

Return values 

Value 

S_OK 
E_FAILED 
FAILED (hr) 



Description 

Function completed successfrilly. 
No engine could be found. 
Appropriate error message. 



©_ 1 995-2000 Microsoft CpHJoration AH rights reserved. 



Microsoft Speech SDK 
with SAPI 5.0 



[This is preliminary documentation and subject to change.] 
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ISpSREngine 



The speech recognition engine implements the interface ISpSREngine. 
Note: The ISpSREngine interface inherits from ISpCFGEnRineClient . 
Methods in Vtable Order 



ISpSREngine Methods 
SetSite 

Ge tlnputAudioFormat 

RecognizeStream 

SMRpcpProfile 

OnCreateGra 

LoadProprietaryGrammar 

Unlo adProprietaryGrammar 

SetProprietaiyR^^ 

SetP roprietaryRuleldState 

LoadSLM 

UnloadSLM 

SetSLMState 
Se tWordSequencePata 
SetTextSelection 
IsPrqnonn 

OnCreateRecoContext 
OnPeleteRec^^^ 

PrivateCall 
SetAdaptationData 

S et PropertyNum 

GetPropertyNum 

SetPropertyS tring 

Ge tPropertyString 

SetGrammarState 



Description 

Sets the ISpEngineSite interface for the engine to use. 

Gets the format of the input audio stream. 

Begins recognition processing on a stream. 

Sets the profile information of the recognition profile 
token. 

Creates a text buffer structure and returns a pointer to it. 

Removes the text buffer structure. 

Loads an engine specific grammar. 

Unloads the engine specific grammar. 

Sets the proprietary grammar rule state. 

Sets the proprietary grammar rule ID state. 

Loads an engine specific statistical language model 
(SLM). 

Unloads an engine specific statistical language model 
(SLM). 

Sets the initial state of the SR engine's SLM. 

Sets the SR engine word sequence data. 

Copies the currently selected text into the grammar. 

Gets the IPA pronunciation of a word's pronunciation id. 

Sets the driver context cookie to NULL. 

Notifies the engine that a recognition context is being 
destroyed. 

Gets or sets miscellaneous information about the engine. 

Sets the SR engine text data associated mth the language 
model adaptation. 

Sets the numerical property attribute information of the 
SR engine. 

Retrieves the numerical property attribute information of 
the SR engine. 

Sets the text property attribute information of the SR 
engine. 

Retrieves the text property attribute information of the SR 
engine. 

Changes the state of a proprietary to determine if specific 
grammar rules should be recognized. 
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© 1995-2000 Microsoft CoTpomtm AWn^ts resen'.ed. 



[This is preliminary documentation and subjeci; to change,] 



ISpSREnginer.SetSite 



ISpSREngine::SetSite sets the IS^EngineSite interface for the engine to use. It also passes the SAPI 
5 CFG language model if it is available. 

HRESULX SetSite( 

I Sp SREngineS ite *pSite 

) ; 

Parameters 

pSite 

Pointer to the ISpEngineSite interface of the engine to use. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_OUTOFMEMORY Exceeded available memory, 

FAILED(hr) Appropriate error message. 

© l?95j32000 Microsoft Corporation. All jights reserved. 

[This is preliminaiy documentation and subject to change, j ^p- 

ISp SREngine : : Getlnput AudioFormat 

ISpSREngine::GetInputAudioFormat gets the format of the input audio stream. 

HREStJLT Get Input AudioFormat ( 

const GtriD *pSourceFoJcmatld, 
const WAVEFORMATEX *pSourceWFEX, 
QUID *pDesiredFonnatId, 

WAVEFORMATEX * *ppCoMemDesiredWFEX, 
ULONG *pulBasicBlock3ize 

); 

Parameters 

pSourceFormatId 

The GUID of the source file format. Not currently used. 
pSourceWFEX 

[in] Address of the WAVEFORMATEX structure containing the wave file format information. 
pDesiredFormatId 
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The GUID of the intended format. 
ppCoMemDesiredWFEX 

The complete wave file format information, 
pulBasicBlockSize 

The basic block size of the wave based on the sampling rate. If the driver does not use a fixed 
block size, zero is passed back. 

Return values 



Value Description 

S_OK Function completed successfully. 
SPERR__FORMAT_NOT_SUPPORTED A local id was not found or is not supported. 

E_OUTOFMEMORY Insufficient memory to allocate acoustic model. 

E_F AIL Speech user is invalid or not initialized. 

E^UNEXPECTED Sampling rate is not valid. 

FAILED (hr) Appropriate error message. 

©_1995-20g0 Microsoft CorBoration, All rights re_served. 

[This is preliminaiy documentation and subject to change,] 

ISpSREngine: iRecognizeStream 

ISpSREngine::RecognizeStream begins recognition processing on a stream. The processing 
continues imtil the buffer is empty or is explicitly stopped. This method is implemented by the 
application. 

HRESULT Function ( 

REFGUID rguidFmtId, 
const WAVEFORMATEX *pWaveFormatEXf 

handle' " hRequestSync, 

HANDLE hDataAvailablef 

HANDLE hExlt, 

BOOL fNewAudioStreairif 

BOOL fReal TimeAndio, 

ISpOb j ectToken s *pAud±oOhjectToken 

); 

Parameters 

rguidFmtld 

[in] The REFGUID for the format to recognize 
pWaveFormatEx 

[in] Address of a WAVEFORMATEX structure describing the input format. 
hRequestSync 

[in] Handle to the task queue allowing or denying stream synchronization. 
hDataAvailable 

[in] Handle to the event indicating available data. 

hExit 

[in] Handle to exit event. 
JNewA udioStream 
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[in] Indicates whether the input is a new stream or not. TRUE means it is a newly created 
stream; FALSE otherwise. 
JRealTimeAudio 

[in] Indicates whether the input is real time audio or not. TRUE means it is real time audio; 
FALSE otherwise 
pAudioObjectToken 

[in] The object token interface for the stream. 

Return values 

Value Description 

S_OK Function completed successfully. 

FAILED (hr) Appropriate error message. 

© 1995-2000 Micrpsofti:orpgratipJi, A]] righB reserved 



[This is preliminary documentation and subject to change.] 

ISpSREngine: rSetRecoProfile 

ISpSREngine::SetRecoProfile sets the profile information of the recognition profile token. 

HRESULT SetRecoProfile( 

ISpOb j ectToken *pProfile 

); 

Parameters 

pProfde 

Address of an ISpObjectToken object that contains the recognition profile token information. 
Return values 

Value Description 

S_OK Function completed successfully. 

E__OUTOFMEMORY Exceeded available memory. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation All rights reser\'ed 



[This is preliminary documentation and subject to change] 

ISpSREngine: lOnCreateGrammar 

ISpSREngine::OnCreateGrammar creates a text buffer structure and passes back a pointer to it as 
the ppvEngineGrammar cookie which the speech recognition (SR) engine will receive as part of the 
SPTEXTBUF transition. 
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HRESULT OnCreateGrammar ( 

void *pvEngineRecoContejct f 

SPGRAMMARHAMDLE hSAPIGrawmar , 
void **ppvEnglneGranmar 



Parameters 



pvEngimRecoContext 

[in] The engine's recognition context. 
hSAPIGrammar 

[in] Handle to the SAPI grammar. 
ppvEngineGrammar 

[out] Address of a pointer to a ppvEngineGrammar that contains the grammar cookie. 
Return values 

Value Description 

S OK Function completed successfully. 

E_INVALIDARG One or more arguments are invaUd. 

E_OUTOFMEMORY Exceeded available memory. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Co rpo ration. All rights resented 



[This is preiiniinary documentation and subject to change.] 

ISpSREngine: lOnDeleteGrammar 

ISpSREngine::OnDeleteGrammar removes the text buffer structure. 

HRESULT OnDeleteGrammar { 
void PpvEngineGrammar 

); 

Parameters 

pvEngineGrammar 

[in] Address of the text buffer structure that is being removed. 

Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG One or more arguments are invalid. 

FAILED(hr) Appropriate error message. 



€) 1995-2000 Microsoft Corporation. _A11 rights jeserved 
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[This is preliminaiy documentation and subject to change, j 

ISpSREngme::LoadProprietaryGraiiimar 

ISpSREngine;:LoadProprietaiy Grammar loads an engine with either specific or proprietary 
grammar. 

HREStJLT LoadProprietaryGrananar ( 
void *pvEngineGrammar, 
REFGUID rguidParam, 
const WCHAR *pszStringParam, 
const void *pvDataParam, 
DLONG ulDataSize, 
SPLOADOPTIONS Options 

); 



Parameters 



pvEngineGrammar 

[in] The address of the driver's grammar cookie. 
rguidParam 

[in] Unique identifier of the grammar. 
pszStringParam 

[in, string] Address of a null-terminated string containing proprietary grammar string 

parameters. 
pvDataParam 

[in] Pointer to the grammar image. 
ulDataSize 

[in] Size, in bytes, of the grammar image. 
Options 

[in] One of the grammar loading options specified in the SPLOADOPTIONS enumeration 
sequence. 

Return values 



Value Description 

S_OK Function completed successfully. 

E_INVALIDARG pvDataParam or ppvEngineGrammar is invalid or bad. 

E_OUTOFMEMORY (hr) Insufficient memory available for allocations. 

FAILED (hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation. All rights reserved 



[This is preliminary^' documentation and subject to change.] 

ISpSREngine::UnloadProprietaryGrammar 

ISpSREiigine::UiiloadProprietaryGraminar iinloads the engine specific grammar. 
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HRESULT UnloadProprietaryGrammar ( 
void *pvEnglneGraxnmar 

); 

Parameters 

pvEngineGrammar 

[in] Address of the driver's grammar cookie. 

Return values 



Value Description 

S_OK Function completed successfully. 



P. J995-2000 MJcrospft Coipw:ation,AlLri£hts reserved 



[This is preliminary documentation and subject to change.] ^ 

ISpSREngine::SetProprietaryRuleState 

ISpSREngine::SetProprietaryRuleState sets the proprietary grammar rule state. 

HRESULT SetProprietaryRuleState { 

void pvEngineGrammar f 

const WCHAR ^pszName, 

const WCHAR -^pszyalue, 

S PRULESTATE NewS ta t e , 

UliONG -^pcRal esChanged 

); 

Parameters 

pvEngineGrammar 

[in] The engine's proprietary grammar rule. 
pszName 

[in, string] Address of a null-terminated string that contains the grammar rule name 
information. 

pszValue 

[in, string] Address of a niill-terminated string that contains the grammar rule value 
information, 
NewState 

[in] One of the grammar rule states specified in the SPRULESTATE enumeration sequence. 
pcRulesChanged 

[out] The number of grammar rules being set. 

Return values 
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Value Description 

S_OK Function completed successfully. 

E_INVALIDARG pvEngineGrammar is invalid or bad. 

FAILED(hr) Appropriate error message. 



© 1995-2000 Mjcrosoft_Cg^^^ AH ri^ts„reserved. 



[Tliis is preliminarj'^ documentation and subject io change.] 

ISpSREngine: : SetProprietaryRuleldState 

ISpSREngine::SetProprietaryRuleIdState sets the propriety grammar rule ID state. 

HRESULT SetProprietaryRuleldState ( 
void -^p-^ETigineGraxnmar, 
DWORD dwRuleld, 
SPRULSSTATE NewState 

); 

Parameters 

pvEngineGrammar 

[in] The engine's proprietary grammar rule. 
dwRuleld 

[in] The engine propriety grammar rule identifier. 

NewState 

[in] One of the grammar rule states specified in the SPRyLESTATE enumeration sequence. 
Return values 

Value Description 

S_OK Function completed successfully. 

E INVALIDARG One or more arguments are invaUd. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corpomtion All fmhis resen'ed . 



[This is preliminary documentation and subject to change.] 

ISpSREngine: rLoadSLM 

ISpSREngine: :LoadSLM loads an engine specific statistical language model (SLM). 

HRESULT LoadSr.M( 

void -^p-vEngineGrammar J 

const WCHAR *pszTopicName 

); 
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Parameters 

pvEngineGrammar 

[in] The current grammar for the engine. 
pszTopicName 

[in, string] Address of a null-terminated string that specifies the SLM name information. The 
default SLM is loaded if the value of pszTopicName is NULL. 

Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG pvEngineGrammar is invalid or bad. 

E_OUTOFMEMORY Exceeded available memory. 

FAILED(hr) Appropriate error message. 



ISpSREngine::UnloadSLM unloads an engine specific statistical language model (SLM). 

HRESULT UnloadSLMC 

void *pvEngiiieGraimar 

); 

Parameters 

pvEngineGrammar 

[in] The current grammar for the engine. 

Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG pvEngineGrammar is invalid or bad. 

FAILED(hr) Appropriate error message. 



© 1_995~2000 Microsoft Corporation, AH rights jeserved 



[This is preliminary^ documentation and subject to change/j 




ISpSREngine: :UnloadSLM 



© 1 995-2000 Microsoft Corporation All rights reserved 



[This is preliminary^ documentatioii and subject to change.] 




ISpSREngine: :SetSLMState 
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ISpSREngine::SetSLMState sets the initial state of the SR engine's statistical language model 
(SLM). 

HRESULT SetSLMState( 

void *pvEngineGraimar, 
SPRULESTATE NewState 

); 

Parameters 

pvEngineGrammar 

[in] The cxjrrent grammar for the engine. 
NewState 

[in] One of the gramme rule states specified in the SPRULESTATE enumeration sequence. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_riSfVALIDARG One or more arguments are invalid. 

FAILED(hr) Appropriate error message. 

© 1^95-2000 Microsoft Cgr(>qmtion_M\n^ts reserved. 



[This is preliminaiy docimientation and subject to change.] 

ISpSREngine: : SetWordSequenceData 

ISpSREngine::SetWordSequenceData sets the SR engine word sequence data. 

HRESULT SetWordSequenceData ( 

void *pvEngineGrarmarr 
const WCHAR *prext, 
ULONG cchText, 
const SPTEXTSELECTIONINFO *pInfo 

); 

Parameters 

pvEngineGrammar 

[in] The current grammar for the engine. 

pText 

[in] The text selection information. 
cchText 

[in] The length, in characters, of the text buffer. 

pinfo 

[in] Address of the SPTEXTSELECTIONINFO structure that contains the sequence 
information. 

Return values 
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Value Description 

S OK Function completed successfully. 

F AILED(hr) Appropriate error message. 



L1995-2000 Microsoft Con>oration. A!J rights_reserved. 



[This is preliminary'' documentation and subject to change.] 1^ 

ISpSREngine: :SetTextSelection 

ISpSREnginertSetTextSelection copies the currently selected text into the grammar. 

HRESULT SetTextSelection { 

void *pvBngineGraimar, 
const SPTEXTSELECTIONINFO ^plnfo 

); 

Parameters 

pvEngineGrammar 

[in] The current grammar for the engine. 

pinfo 

[in] The text selection information. 
Return values 

Value Description 

S_OK Function completed successfully. 

E INVALIDARG pvEngineGrammar is invalid or bad. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation. All righ ts r eserved . 

^^^^ 

[This is preliininar)^ documentation and subject to change.] 

ISpSREngine: :IsPronounceable 

ISpSREngine: tIsPronounceable gets the International Phonetic Alphabet (IP A) pronunciation of a 
word's pronunciation id. 

HRESULT IsPronounceable ( 

void •^p^/'DrvGraImarf 

const WCHAR -^pszWord, 

BOOL *pfPronounceahle 

); 

Parameters 
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pvDrvGrammar 

[in] The driver's grammar cookie. 
pszWord 

[in] The word to test. 
pfPronounceable 

[out] Flag indicating the results of the test. TRUE, if a pronunciation was found; FALSE, 
otherwise. 

Return values 

Value Description 

S_OK Method completed successfully. 

E__NOTIMPL The SLM interface is not available. 

FAILED(hr) Appropriate error message. 

See Also 

ISpRecoGramm :IsPronounceable 



ISpSREngine::OnCreateRecoCont€xt notifies the engine that a recognition context is being 
created. 



HRESULT OnCreateRecoContext ( 
void *pvSapiCon text, 
vo id * * ppvEnglnBCon text 

); 

Parameters 

pvSapiContext 

[in] Handle to the recognition context. 
ppvEngineContext 

[out] Pointer to engine-specific information. 

Return values 

Value Description 

NOERROR Call succeeds. 



© 1 995-2000 Microsoft Corporation. AU Xigh^s resented. 



[This is preliminary documentation and subject to change.] 




ISpSREngine: :OnCreateRecoContext 



9 1995-2000 Microsoft Corporation All rights jeser\'ed 



file://C:\WINDOWS\TEMP\~hh38F6.htm 



12/28/00 



Engine-Level Interfaces 



Page 50 of 75 



[This is preiiminary documentation and subject to change.] 




ISpSREngine: rOnDeleteRecoContext 



ISpSREngine::OnDeleteRecoContext notifies the engine that a recognition context is being 
destroyed. 

Note: This method performs no operation and returns S_OK. 

HRESULT OnDeleteRecoContext ( 
void *pvEngineCont€xt 

); 

Parameters 

pvEngineContext 

[in] Pointer to the engine context value retumed from a previous call to 
ISpSREn^ine;:OnC^^^ for this context. 

Return values 

Value Description 

S_OK Only possible return value. 



ISpSREngine::PrivateCall gets or sets miscellaneous information about the engine, 

HRESULT PrivateCalK 

VOID *pvEngineCtxtCookie , 
void ^pCallFramBr 
ULONG ul CallFrameSi ze , 

); 

Parameters 

pvEngineCtxtCookie 

[in] The drivers recognition context cookie. 
pCallFrame 

[in] Pointer to the private data. 
ulCallFrameSize 

[in] Size, in bytes, of the private data. 

Return values 



© } 9^^'1^9.M^^losgfiS9V?(>V^mi AH rights reserved 



[This is preliminary documentation and subject to change.] 




ISpSREngine: tPrivateCall 
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Value Description 

S_OK Function completed successfully. 

E_INVALIDARG pCallFrame is not a recognized value. 

FAILED (hr) Appropriate error message. 



) 199>2p0p Microsoft Cpr^ppration^.AlLi^^^^ 



[This IS preiiroinarj^ docimentalion and subject to ckmge.] 

ISpSREngine: rSetAdaptationData 

ISpSREngine::SetAdaptationData sets the SR engine text data associated with the language model 
adaptation. 

HHESULT SetAdaptationData ( 

void *pvEngineConteKt , 

const WCHAR -^pCoMemAdaptationData, 
const ULONG cch 

); 

Parameters 

pvEngineContext 

[in] Address of the SR engine context information. 
pCoMetnAdaptationData 

Address of the adaption data information. Applications implementing this method must call 

CoTaskMemFreeO to free memory associated with this string. 

cch 

The number of SR engine text data items. 
Return values 

Value Description 

S_OK Function completed successfully. 

E_OUTOFMEMORY Exceeded available memory. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation All rights resented . 



[This is preiiminaty documentation and subject to change.] 

ISpSREngine: : SetPropertyNum 

ISpSREngine::SetPropertyNum sets the numerical property attribute information of the SR engine. 



HRESULT SetPropertyNum ( 
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SPPROPSRC eSrc, 
void *pvSrcObj , 

const WCHAR *pName, 
LONG lvalue 

); 

Parameters 

eSrc 

[in] One of the recognition context types specified in the SPPROPSRC enumeration sequence. 
pvSrcObj 

[in] Address of the object containing the property name and value information. 
pName 

[in] Address of the string containing the property attribute name information. 
IValue 

[in] Address of the value containing the property attribute value information. 
Return values 

Value Description 

S_OK Function completed successfully. 

FAILED(hr) Appropriate error message. 

©J. 2.^5^2000 Microsoft Corporation. Mpghts reseryed. 



[This is preliminary documeniation and subject to change,] 

ISpSREngine: iGetPropertyNum 

ISpSREngine::GetPropertyNum retrieves the numerical property attribute information of the SR 
engine. 

HRESULT GetPropertyNum( 

SPPROPSRC eSrc, 
void *pvSrcObj , 

const WCHAR *pNamef 
LONG * IValue 

); 

Parameters 

eSrc 

[in] One of the recognition context types specified in the SPPROPSRC enumeration sequence. 
pvSrcObj 

[in] Address of the object containing the property name and value information. 

pName 

[in] Address of the string containing the property attribute name information. 

IValue 

[out] Address of the value containing the property attribute value information. 
Return values 
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Value 

S_OK 

FAILED(hr) 



Description 

Function completed successfully. 
Appropriate error message. 



© 1995-2000 Microsoft Corporatior! AlLrights reserved. 



[This is preliminm7 documentation and subject to change.] 



ISpSREngine: rSetPropertyString 



ISpSREngine::SetPropertyString sets the text property attribute information of the SR engine. 

HRESULT SetPropertyString ( 



const WCHAR *pNaine, 
const WCHAR *p Value 

); 

Parameters 

eSrc 

[in] One of the recognition context types specified in the SPPROP SRC enumeration sequence, 
pvSrcObj 

[in] Address of the object containing the property name and value information. 
pName 

[in] Address of the string containing the property attribute name information. 
pValue 

[in] Address of the value containing the property attribute value information. 
Return values 



Value Description 

S_OK Function completed successfully. 

F AILED(hr) Appropriate error message. 



ISpSREngine::GetPropertyString retrieves the text property attribute information of the SR 
engine. 

HRESULT GetPropertyString( 



SPPROPSRC 
void 



eSrCf 
*pvSrcObj , 



© ^ 995j^2000 Microsoft Coi^ rights_res_erved 



[This is preliminary documentation and subject to change.] 




ISpSREngine: rGetPropertyString 



SPPROPSRC 



eSrc, 
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void *pvSrcObj , 

const WCHAR ^pName, 
WCHAR * -^ppCoMemValue 

); 

Parameters 

eSrc 

[in] One of the recognition context types specified in the SPPROPSRC enumeration sequence. 
pvSrcObj 

[in] Address of the object containing the property name and value information. 
pName 

[in] Address of the string containing the property attribute name information. 
ppCoMem Value 

[out] Address of a pointer to a string that receives the property attribute value information. 
Applications implementing this method must call CoTaskMemFreeQ to free memory 
associated with this string. 

Return values 

Value Description 

S OK Fimction completed successfully. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Miq:o_softCprpomtipn^AHng^ feseived. 



[This is preliminar\'' documentation and subject to change,] 

ISpSREngine: :SetGrammarState 

ISpSREngine: :SetGrammarState changes the state of a proprietary to determine if specific 
grammar rules should be recognized. The SR engine must implement this method itself. If the engine 
does not support proprietary grammars, then S_OK may be returned. 



HRESULT SetGrammarState ( 

void *pvEngineGrairmar r 

S PGRAMMARSTATB eGrammarState 

); 

Parameters 

pvEngineGrammar 

[in] Void pointer to the specified grammar for the context. 
eGrammarState 

[in] Flag of type SPGRAMMARSTATE indicating the new state of the grammar. 
Return values 

Return values are specific to the engine implementation. 

© 1995-2000 Microso ft C orporation All rig h ts reserved 
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Microsoft Speech SDK 
with SAPI 5.0 



[This is preliminary dociimenlalion and subject to change.] 

ISpSREngineSite 

The interface ISpEngineSite is implemented by SAPI and is called by the engine to get audio data 
and signal detected sound events, and return recognition information. 

Methods in Vtable Order 



ISpSREngineSite Methods 
Read 

DataAvaik 

SetBnfferNotiiySize 

ParseFromTransitions 

R^ecpgnition 
AddEvent 

S ynchronize 

GetWordlnfo 

SetWordaientContext 

GetRuIelnfo 

SetRuleClientContext 

GetStatelnfo 

GetResource 

GetTransitionPro^ 

IsAIternate 

GetMaaiAlter^^^ 

GetContextMa]^^ 
UpdateRecoPos 



Description 

Reads the input stream in a safe thread method. 

Retrieves the amount of data that can be read. 

(This method is not yet implemented) 

Parses an ISpPhraseBuilder result from a list of 
transitions. 

Indicates an end of the phrase and to start recognition. 

Retrieves a RecoContext event handle from the SR 
engine. 

Allows the SR engine to process changes in its active 
grammar state. 

Retrieves information for CFG word. 

Sets an engine-defined context pointer for a CFG word. 

Retrieves information about a CFG rule. 

Sets an engine-defined context pointer for a CFG rule. 

Retrieves transition state information for CFG transition. 

Retrieves a named resource from a grammar. 

Retrieves the SR engine transition property information. 

Determines whether one rule is an alternate of the other. 

Passes back the maximum number of alternates that 
should be generated for the specified rule. 

Passes back the maximum number of alternates that 
should be generated for the specified recognition context. 

Returns the current position of the recognizer in the 
stream. 



©_1 995-2000 Microsoft CoH'oration.. All rights resery_ed. 
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ISpSREngineSite: .Read 
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ISpSREngiiieSite::Read reads the input stream in a safe thread method. 



HRESULT Function ( 
void *pv, 
ULONG cb, 
ULONG *pcbRead 

); 

Parameters 

pv 

[in] The input stream. 

cb 

[in] Size, in bytes, of the input stream. 
pcbRead 

[out] Number of bytes read. 

Return values 

Value 

S_OK 

SPERR_STREAM__NOT_ACTIVE 
E_POINTER 

STG_E_ACCESSDENIED 
FAILED (hr) 

© 1 995-2000_Microspft CoiEoratioa^ AU jjgh^^ resented. 



Description 

Function completed successfully. 

Input stream is not defined or active. 

At least one oi pcbRead or pv are invalid or bad. 

Input stream is read only and no bytes will be read. 

Appropriate error message. 



[This is preliminary documentation and subject to change.] 

ISpSREngineSite: iDataAvailable 

ISpSREngineSite::DataAvailable retrieves the amount of data that can be read using 
IS p SREngineSite: iRead without blocking. 

HRESULT DataAvailable ( 
ULONG pch 

); 

Parameters 



pcb 

[out] The amount, in bytes, of data available. For audio streams this is the actual amount. For 
non-audio streams, this is the minimum known amount. 

Return values 
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Value 

S_OK 

E__INVALIDARG 

E_POINTER 

FAILED(hr) 



Description 

Function completed successfully. 
ullStartPos is less than the stream minimum. 
pullDataAvailahle or pJNoBlock is invalid or bad. 
Appropriate error message. 



© 1995-2000 M icrosoft Corp oration AH rights reserved 



^This is preliminar}^ documentation and subject to change,] 




ISpSREngmeSite::SetBufferNotifySize 



Note: This method is not implemented. 

HRESULT SetBufferNotifySize( 
XJLONG cbSize 

); 

Parameters 

cbSize 

[in] The minimum amount of data that should be available before the event is set. 
Return values 

Value Description 

S_OK Function completed successfully. 



ISpSREngineSite::ParseFromTransitions 



ISpSREngineSite::ParseFromTransitions parses an ISpPhraseBuilder result from a list of 



Called by the SR engine to get an SPPHRASE. This method uses a greedy top-down search 
algorithm to find the semantic properties. 

HRESULT ParseFromTransitions ( 

const SPPARSEINFO *pParseInfOr 
I SpPhr a s eBu i 1 de r * *ppPhra s e 

); 



© 1995-2000 Microsoft Corporatiotk AU rights^reserved. 
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transitions. 



file://C:\WEvfDOWS\TEMPWhh38F6.htm 



12/28/00 



Engine-Level Interfaces 



Page 58 of 75 



Parameters 

pParselnfo 

[in] Address of the SPPARSEINFO structure containing phrase information. 
ppPhrase 

[out] Address of a pointer to an ISpPbraseBuilder interface that receives the phrase 
information. 

Return values 

Value Description 

S_OK Function completed successfully. 

FAILED (hr) Appropriate error message. 



©. 1995-2p00_Micrgsoft n^hts reserved. 



[This is preliminan^ dociimentation and subject to change.] liP' 

ISpSREngineSite: iRecognition 

ISpSREngineSite:: Recognition indicates the end of a phrase and initiates recognition. 

The phrase can be either a hypothesis or a final resuh. If it is a hypothesis, a global hypothesis 
notification is issued to all interested recognition contexts. Otherwise, a final global hypothesis 
notification is issued to all interested contexts. A final phrase notification is issued to the target 
granmiar identified by the SR engine. 

ISRS?£ngineSite::AddEvent with a SPEI_PHRASE_START as the event type must precede the call 
to ::Recognition. SAP! does enforce the phrase start and recognition order. pResultlnfo must be 
allocated by CoTaskMemAlloc() so that ownership can pass to SAPI. 

HRESULT Recognition ( 

SPRSCORESULTINFO *pResul tinfo 

); 

Parameters 

pResultlnfo 

[in] Pointer to type SPRECORESULTINFO indicating the results. 
Return values 

Value Description 

S_OK Function completed successfully and to continue 

recognition. 

S_FALSE Function completed successfully and the engine can 

terminate recognition without reading the rest of the 
stream. 
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ISpSREngineSite: : AddEvent 

ISpSREngineSitetrAddEvent retrieves a RecoContext event handle from the SR engine. 

HRESULT AddEvent ( 

cons t S PEVENT *pEven t , 

SPRECOCONTEXTHANDLE hCon text 

); 

Parameters 

pEvent 

[in] Address of the SPEVENT structure containing the event information. 
hContext 

[in] The RecoContext is the event handle passed to SR Engine from S API through 
ISpSREn^ine::OnCreateRecoContext > A NULL value in hContext indicates the event is a 
global one. 

Return values 

Value Description 

S_OK Function completed successfully. 

E INVALIDARG At least one of pEvent or hContext is invalid or bad. 

Alternatively, it indicates an event is being added to an 
inappropriate mode. 

E_POINTER Invalid pointer. 

SPERR_STREAM_POS_INVALID The current audio stream offset is greater than either the 

current seek position or the last sync position. 
Alternatively, if the event stream is not initialized the 
stream position is not zero. 

FAILED(hr) Appropriate error message. 

© J995-2000McXQSoft Corpojatioii. All rights reserved. 



[This is preliminary documentation and subject to change.] 

ISpSREngineSite: rSynchronize 

ISpSREngineSite: rSynchronize allows the SR engine to process changes in its active grammar 
state. 

HRESULT Synchronize ( 
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ULONGLONG ullStreamPos 

); 

Parameters 

ullStreamPos 

[in] The position within the audio stream to stop processing. 
Return values 

Value Description 

S_OK Function completed successfully and to continue 

recognition. 

SPERR_STREAM_NOT__ACTIVE Stream is not initialized. 

SPERR_STREAM_POS_INVALID Stream position is either greater than the current seek 

position or less than the last synchronized position. 

S_FALSE Function completed successfully and the engine can 

terminate recognition v^thout reading the rest of the 
stream. 

FAILED (hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation. All rights resented . 

[This is preliminary documentation and subject to change.] ^Sf 

ISpSREngineSite: :GetWordInfo 

ISpSREngineSite::GetWordInfo retrieves information for CFG word, 

HRESULT GetWordInfo( 

SPWORDENTRY *pWordEn try, 
SPWORDINFObPT Op ti ons 

); 

Parameters 

pWordEntry 

Address of the SP WORDENTR^^ structure that contains the grammar word entry information. 
The following members may be allocated with CoTaskMemAllocQ and if so, must be freed 
with CoTaskMemtaskFreeQ when no longer required. 
pWordEntry->pszDisplayText 
pWordEntry->pszLexicalForm 
pWordEntry->aPhoneId 
Options 

One of the grammar word options specified in the SPWORDINFOOPT enumeration. 
Return values 
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Value 

S_OK 

E INVALIDARG 



Description 

Function completed successfully. 

Options cannot include both SPWIO_NONE and 
SPWIO_WANT_TEXT 

Not enough memory to complete the operation. 

Appropriate error message. 



E_OUTOFMEMORY 
FAILED (hr) 



© 1995-2000 Microsoft Corporation. AXi rights resented . 
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ISpSREngineSite::SetWordCIientContext 



ISpSREngineSiterrSetWordClientContext sets an engine-defined context pointer for a CFG word. 

HRESUIiT SetWordClientContext { 
SPWORDPIANDLE hWord, 
void *pvCl i en tCon t ext 

); 

Parameters 

hWord 

The handle for a word. 
pvCUentContext 

Pointer to the word's client context. 

Return values 

Value Description 

S_OK Function completed successfully. 

FAILED (hr) Appropriate error message. 



ISpSREngineSite::GetRuleInfo retrieves information about a CFG rule. 

HRESULT GetRuleInfo( 

S PRULEENTRY *pieu 1 eEn try, 
S PRULE INFOOPT Options 

); 



© 1995-2000 Microsoft Corppra^^^ AUn^^ItS-f^served 
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ISpSR£ngineSite::GetRuIeInfo 
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Parameters 

pRuleEntry 

[in, out] Address of the SPRULEENTRY structure that contains the grammar rule entry 
information. 
Options 

[in] One of the granraiar rule options specified in the SPRULEINFOO^^ enumeration 
sequence. 

Return values 

Value Description 

S OK Function completed successfully. 

FAILED (hr) Appropriate error message. 

©1995-2000 Microsoft CorEgrat]on„ Aljjights resented 
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ISpSREngineSite::SetRuleClieiitContext 

ISpSREngineSite::SetRuleClientContext sets an engine-defined context pointer for a CFG rule. 

HRESULT SetRuleClientContext ( 
SPRULEHANDLE hRule, 
void *pvCI i en t Con text 

); 

Parameters 

hRule 

Handle of rule that was recognized. 
pvClientContext 

Pointer to the rule's client context. 

Return values 

Value Description 

S OK Function completed successfiiUy. 

FAILED (hr) Appropriate error message. 

© 1995-2000 Micro soft Cor poration. AH rights resented . 

[This is preliminary documentation and subject to change] 

ISpSREngineSite: :GetStateInfo 
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ISpSREiigineSite::GetStateInfo retrieves transition state information for CFG transition. 

HRESULT GetStateInf o ( 

SPSTATEHANDLK hStater 
SPSTATEINFO *pStateXnfo 

); 

Parameters 

hState 

Handle to the current state. 
pStatelnfo 

The state information. 



Return values 

Value 

S_OK 

FAILED (hr) 



Description 

Function completed successfully. 
Appropriate error message. 



©i 9^5-2000 Microsoft COTQi^tlon^AlLri^htsjeserved 



[This is preliminar)^ documentation and subject to change.] 

ISpSREngineSite: :GetResource 

ISpSREngineSite::GetResource retrieves a named resource from a grammar. 
Note: This method is not currently implemented. 

HRESULT GetResource{ 

SPRULEHANDLE hRule, 

WCHAR '^*ppCoMeniResource 

) ; 

Parameters 

hRuIe 

[in] The rule handle. 
ppCoMemResource 

The resource associated with the rule. AppUcations implementing this method must call 
CoTaskMemFreeO to free memory associated with this resource. 

Return values 



is 
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Value Description 

S_OK Function completed successfully. 

E POINTER ppCoMemResource is invalid or bad. 

EJSfOTIMPL Method is not implemented. 

FAILED (hr) Appropriate error message. 



© 1995-2000 M icroso ft Corpo ration. AH rights reserved 



[This is prelimiriar}^ documetitatioo and subject to change.] 

ISpSREngineSlte::GetTransitionProperty 

ISpSREngineSite::GetTransitionProperty retrieves the SR engine transition property information. 

HRESULT GetTransitionProperty ( 
SPTRANSITIONID ID, 

SPTRANS ITIONPROPERTY * * ppCoMemProperty 

); 

Parameters 

ID 

[in] The transition identifier. 
ppCoMemProperty 

[out] Address of a pointer to a SPTMNSITIONPROPERTY that receives the transition 
information. Applications implementing this method must call CoTaskMemFreeQ to free 
memory associated with this resource. 

Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG One or more arguments are invalid. 

E_POINTER Invalid pointer. 

E_OUTOFMEMORY Exceeded available memory. 

FAILED(hr) Appropriate error message. 

© 1995-2000 Micr oso ft Corporation All rights resented 

[This is preliminary documentation and subject to change,] Igf 

ISpSREngineSite: :IsAlternate 

ISpSREngmeSite::IsAlternate determines whether one rule is an alternate of the other. 
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HRESULT IsAlternate{ 

SPRULEHANDLE hPriRule, 
SPRULEHANDLE hAltRule 

); 

Parameters 

hPriRule 

[in] The primary rule. 
MltRule 

[in] The alternate rule to be checked. 
Return values 

Value Description 

S_OK hAltRule is an alternate of hPriRule, 

S_FALSE hAltRule is not an alternate of hPriRule, 

FAILED (hr) Appropriate error message. 



© l?95-200p Microsoft Coiporation AUrightsxeser\'ed 



[This is preliminary documentation and subject to change.] 

ISpSREngineSite: :GetMaxAlternates 

ISpSREngineSite::GetMaxAlternates passes back the maximum niimber of alternates that should 
be generated for the specified rule. 



HRESULT GetMaxAlternatesC 
SPRULEHANDLE ilRuIe, 
ULONG *pulNvmAlts 

); 

Parameters 

hRule 

[in] The rule to check. 
pulNumAlts 

[out] The maximum number of alternates for the rule. 
Return values 

Value Description 

S OK Function completed successfully. 

E_POINTER pulNumAlts is invalid or bad. 

FAILED (hr) Appropriate error message. 
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© 1995-2000 Microsoft Corppration._A]l rights reseryed 
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ISpSREngiiieSite::GetContextMaxAlternates 



ISpSREngmeSifeirGetContextMaxAlternates passes back the maximum number of alternates that 
should be generated for the specified recognition context. Engines supporting proprietary grammars 
need to call this to determine how many alternates to generate. For SAPI grammars, it is usually 
easier to use the IS|)SREn£ineSite: :GetMaxA method. 



HRESULT GetContextMaxAlternates ( 
SPRECOCONTEXTHANDLE hContext , 
ULONG *pulNuxttAlts 

); 

Parameters 

hContext 

[in] Handle to the current context. 
pulNumAlts 

[out] The number of possible alternates. 

Return values 

Value Description 

S_OK Function completed successfully. 

E_POINTER pulNumAlts is invalid or bad. 

FAILED (hr) Appropriate error message. 



ISpSREngineSite::UpdateRecoPos returns the current position of the recognizer in the stream to 
SAPL An engine shoidd call this regularly, up to several times a second, regardless of whether it is 
recognizing speech or silence. 



HRESULT XJpdateRecoPos ( 

ULONGLONG ullS treamPos 

); 



© 1995-2000 Microsoft Cpjporation Ail rights resen'ed. 
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ISpSREngineSite: rUpdateRecoPos 



Parameters 
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ullStreamPos 

[out] The current recognizer of the stream position. 



Return values 



Value 

S OK 



Description 

Function completed successfully and to continue 
recognition. 



©-1995-2000 Microsoft Cpregratiqn, AU lights resewed 



Microsoft; Speech SDK 
with SAPI 5.0 




This is preiiminarj^ documentation and subject to change.] 



ISpSRAltemates allov/s alternate word selection and implementation for speech recognition. 
Methods in Vtable Order 



[This is preliminary documentation and subject to change.] 



ISpSRAlternates: :GetAlternates 



ISpSRAltemates:;GetAltemates retrieves a list of alternate words. 

HRESULT GetAlternates ( 

SPPHRASEALTREQUSST *pAl tRequest, 
SPPHRASEALT ' " ^^^ppAlts, 
VhOm *pcAlts 

); 

Parameters 

pAltRequest 

[in] A structure to the requested alternate words. 

ppAIts 

[out] A list of SPPHRASEALT for alternate words. 

pcAlts 

[out] The number of alternates in ppAltslist 



ISpSRAlternates 



ISpSRAlternates Methods 

GetAlternates 

Commit 



Description 

Retrieves a list of alternate words. 

Chooses the lexicon manager's word probability. 



© 1995-2000 Microsoft Corporation. All rights resewed . 
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Return values 

Value Description 

S__OK Function completed successfully. 

FAILED (hr) Appropriate error message. 



©1995-2000 Mkrpsoft Cpn)oratipn^ Al] rights reserved 



[This is preliminat}'^ documentation and subject to change.] 1^ 

ISpSRAlternates: rCommit 

ISpSRAlternates::Commit chooses the lexicon manager's word probability. This allows fine 
adjustments for the decoder to pick the new, alternate words over the current ones. 

HRESULT Commit ( 

SPPHRASEALTREQUEST *pAl tieequest , 
s1pphrase^.t *pAlt, 
void **ppvResultExtra , 

ULONG *pcbResul tExtra 

); 

Parameters 

pAURequest 

[in] A structure to the requested alternate words. 

pAlt 

[in] A structure to alternate words. 
ppvResultExtra 

[out] Additional information for the new results. 
pcbResultExtra 

[out] Size, in bytes, of ppvResultExtra, 

Return values 

Value Description 

S_OK Function completed successfully. 

FAILED (hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation. All rights resented. 

Microsoft Speech SDK ^ 
with SAPI 5.0 ^ 

[This is preliminaty documentation and subject to changcl 

Text To Speech Recognition Engine Manager 
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(DDI-level) 



The following section covers: 



• ISpTTSEngine 

• iSpTtSEngmeSite 



©J ?„^5-2j)00 Microsoft Corporati All rights reserved 
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with SAPI 5.0 




[This is preliminary documenlatioii and subject to change.] 



ISpTTSEngine 



The SAPI speech synthesis (text-to-speech, or TTS) engine (driver) implements an ISpTTSEngine 
interface. 

ISpTTSEngine:: Speak is the primary method called by SAPI to perform speech rendering. SAPI, 
rather than the engine, performs XML parsing of the input text stream. The engine's Speak method is 
handed a linked list of text fragments with their associated XML attribute state. The Speak method 
also receives a pointer to the SpVoice's ISpTTSEngineSite interface. The TTS engine uses this 
interface to queue events and to write the output data. 

Even though SAPI 5.0 is a free-threaded architecture, TTS engine instances will always be called by 
SAPI on a single thread. TTS engines are never directly accessed by applications. SAPI ensures that 
all parameter vaUdation and thread synchronization has been performed properly before calling the 
TTS engine. All calls to the TTS engine in the release build of SAPI are within a try or except block 
to protect applications from faulting. 

Methods in Vtable Order 

ISpTTSEngine Methods Description 

Speak Speaks a text buffer. 

GetOutputFormat Retrieves the output stream format. 



ISpTTSEngine: rSpeak speaks a text buffer according to the associated XML state. 

The Speak method renders the specified linked list of text fragments in the selected output format. 
All XML markups have been removed from the input text; the absolute state has been accumulated 
and stored in a data structure associated with each text fragment. 



1 995-2000 Microsoft Co r poration All rights reserved . 
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HRESULT Speak ( 

DWORD dwSp eakFl ags , 

REFGtJID rgui dForma tid, 

const ^ayeFormatEx *pWaveFonnatEx, 
const SPVTEXTFRAG ^ *pTextFragLlstr 
ISpTTSEngineSite *pOutputSite 

); 

Parameters 

dwSpeakFlags 

[in] Flags defining the attributes of speech. These values are contained in the SPEAKFLAGS 
enumeration. 
rguidFonnatId 

[in] The stream format identifier describing the desired output format. 

wnirm T*.^f SPDFID_Text is specified, the output is sent to a 

-^^^^ text buffer and pTargetWaveFormatEx is NULL. 

conuTrk w„..^ir^^,^«*ir^If SPDFID WaveFormatEx is Specified, the output 
SPDJb ID WaveFormatEx . . x\rK \ rr:x2r\Ty\A a t-itv j + 4. \ 

- type IS a WAyEFORMATC data structure, 

pWaveFormatEx 

[in] Address of a WAVEFORMATEX structure describing the output format. 

Note: WaveFormatEx is the output format when the contents of rguidFormatld is 
SPDFID_WaveFormatEx. 

The contents of pWaveFormatEx is NULL lirguidFormatlD specifies SPDFID_Text. 
pTextFragList 

[in] The fragment link list of type SPyTEXTFRAG to synthesize. 
pOutputSite 

[in] Address of the ISpTTSEngineSite interface of the Sp Voice object where events are queued 
and the output data is written. 

Return values 

Value Description 

S_OK Function completed successfully. 

E_INVALIDARG rguidFormatld or pOutputSite is bad or invalid. 

E^OUTOFMEMORY Exceeded available memory. 

FAILED (hr) Appropriate error message. 

© 1995-2000 Microsoft Corporation. AU rights resented 
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ISpTTSEngine: :GetOutputFormat 

ISpTTSEngine::GetOutputFormat retrieves the output stream format. 

If the specified output format is not supported by the engine, the engine can return either the closest 
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format supported or the default format of the engine. 

HRESXJLT GetOutputFormat ( 

const GUID *pTargetFmtXdr 
const WAVEFORMATEX *pTargetWaveFormatEXr 
GUID *pOutput Forma tXd, 

WAVEFORMATEX **ppCoMemOutputWaveForma tEx 

); 

Parameters 

pTargetFmtId 

[in] Address of the GUID describing the output format desired by the application. 

cpniTTn T If SPDFID_Text is specified, the output is sent to a 

^rui^ lu^i ext ^^^^ ^^^^ pTargetWaveFormatEx is NULL. 

SPDFTD WaveFftrmatFx SPDFID_WaveFormatEx is specified, the output 
hFDi^lD^Wavel^ormatJLx ^^^^ ^ WAVEFORMATEX data structure, 

pTargetWaveFormatEx 

[in] Address of the WAVEFORMATEX structure describing the application's output format. 
IfpTagetFmtId specffies SPDFID_Jext, the contents oi pTargetWaveFormatEx will be NULL. 

The contents of pTargetWaveFormatEx must be set when pTagetFmtId is specified as 
SPDFID_WaveFormatEx. 
pOutputFormatId 

[out] Address of the output format identifier. 

wnP¥n T^vf If SPDFID_Text is specified, 

^rur ext ppCoMemOutputWaveFormatEx is set to NULL. 

If SPDFID_WaveFormatEx is specified, and the 

SPDFTD WaveFormatFx ^^^^^^ ^^PP^" f^™^^^' ^ P^^^^^^ 
5^FDl^lD_Wavel^ormatlLx WAVEFORMATEX structure should be returned 

by the engine. 

PpCoMemOutputWaveFormatEx 

[out] Adddress of the pointer to the WAVEFORMATEX returned by the engine. 

Return values 

Value Description 

S_OK Function completed successfixlly. 

E_OUTOFMEMORY ppCoMemDesiredWaveFormatEx could not be allocated. 

FAILED (hr) Appropriate error message. 



Microsoft Speech SDK 
with SAPI 5.0 
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ISpTTSEngineSite 



ISpTTSEngineSite is implemented on the voice and redirects engine output based on current voice 
settings. 
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Note: The ISpTTSEngineSite interface inherits from ISpEventSink. 



Methods in Viable Order 



GetActions 
Write 



GetRate 
GetVoliime 



ISpTTSEngineSite Methods 



CompleteSki^ 



GetSkipInfo 



Description 

Retrieves the action the engine needs to perform. 

Sends synthesized speech audio data to the TTS engine. 

Retrieves the current TTS engine rate. 

Retrieves the output volume level of speech synthesized 
by an engine. 

Retrieves the number and type of items to be skipped in 
the text stream. 

Retrieves the number of sentences skipped by the engine. 
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ISpTTSEngineSite: :GetActions 



ISpTTSEngineSite:: GetActions obtains the action that it needs to perform. SAPI returns a DWORD 
indicating one of several actions contained in the SPVESACTIONS enumeration. 

DWORD GetActions { void ) ; 

Parameters 

None. 

Return values 

The DWORD indicates whether or not the engine should take any actions. 



ISpTTSEngineSite:: Write sends synthesized speech audio data to SAPI allowing it to send the 
audio data to the output destination. 

SAPI handles sending the audio data to the correct output destination. It is important that any events 
associated with the audio data are queued by calling the ISj)EventSink;: AddEvents method prior to 
calling this method. This ensures proper synchronization of event firing and audio rendering. 
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ISpTTSEngineSite: : Write 
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HRESULT Write { 
const void 
ULONG 
ULONG 

); 

Parameters 



*pBuff, 
*pcbWritten 



pBuff 

Pointer to synthesized speech audio data. The format (resolution) is specified by S API on the 
ISpTTSEngine::Speak call on which this ISpTTSEngineSite interface was passed. 

cb 

The buffer size, in bytes, of pBujf. 
pcb Written 

Pointer to the number of bytes actually copied. 
Return values 



Value Description 

S OK Function completed successfully. 

E_INVALIDARG pBuff is bad or invalid. 

E_POINTER pcbWritten is bad or invalid. 

SPERR_IJNINITIALIZED Output stream can not be initialized. 

FAILED (hr) Appropriate error message. 
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ISpTTSEngineSite: :GetRate 

ISpTTSEngineSite: rGetRate retrieves the current TTS engine rate. 

HRESULT GetRate( 

long *pRateAdjust 

); 

Parameters 

pRateAdjust 

[out] Value specifying the xmits per minute rate for spoken text. 
Return values 



Value Description 

S OK Function completed successfully. 

FAILED(hr) Appropriate error message. 
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[This is preiiminaiy documentation and subject to change,] tpf 

ISpTTSEngineSite: :GetVolume 

ISpTTSEngineSite::Get Volume retrieves the output volume level of speech synthesized by an 
engine, 

HRESULT GetVoluiae( 
USHORT* pusVolume 

); 

Parameters 

pusVolume 

[out] Address of the value that receives the volvime level information. 
Return values 

Value Description 

S_OK Function completed successfully, 

FAILED(hr) Appropriate error message. 

©1995-2000 Microsoft, Coiporation AIUij;hts reserved. 

[This is preliminar}^^ documentation and subject to change.] 

ISpTTSEngineSite: rGetSkipInfo 

ISpTTSEngineSite: iGetSkipInfo retrieves the niunber and type of items to be skipped in the text 
stream. These items can be skipped either forward or backward within the text stream. 

HRESULT GetSkipInfoC 

SPySKIPTYPE *peType, 
long *plNumI terns 

); 

Parameters 

peType 

[out] Address of the SPY SKIPTYPE enumeration that receives the item type information. 
plNumltems 

[out] Address of a value specifying the number of items to skip. 
Return values 
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Value 

S_OK 

FAILED(hr) 



Description 

Function completed successfully. 
Appropriate error message. 
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ISpTTSEngineSite : : CompleteSkip 



ISpTTSEngineSite::CompleteSkip retrieves the number of sentences skipped by the engine and 
passes the count to SAPL 

HRESULT CompleteSkip ( 
long ulNumSkipped 

); 

Parameters 

ulNumSkipped 

[in] Specifies the number of items to be skipped. Negative values result in a skip in the reverse 
direction, while positive values result in a skip forward. A value of zero causes the engine to 
skip to the beginning of the current item of the specified type. 

For example, if the item type were "sentence" and the value of ulNumSkipped is zero, the 
engine will begin the sentence again. Additionally, the engine will skip to the beginning of the 
next sentence if the value of ulNumSkipped is one. Conversely, the engine will skip to the 
beginning of the previous sentence if the value of ulNumSkipped is negative one. 

Return values 

Value Description 

S__OK Function completed successfully. 

FAILED(hr) Appropriate error message. 
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